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Preface 


This manual provides users of the OpenVMS operating system with detailed 
usage and reference information on general purpose routines supplied in the 
OTS$ facility of the Run-Time Library. 

Intended Audience 

This manual is intended for system and application programmers who want to 
call Run-Time Library routines. 

Document Structure 

This manual is organized into two parts as follows: 

• Part I contains a brief overview of the OTS$ routines in Chapter 1. 

• Part II, the OTS$ Reference Section, provides detailed reference information 
on each routine contained in the OTS$ facility of the Run-Time Library. 

This information is presented using the documentation format described 

in OpenVMS Programming Interfaces: Calling a System Routine . Routine 
descriptions appear in alphabetical order by routine name. 

Associated Documents 

The Run-Time Library routines are documented in a series of reference manuals. 
A description of how the Run-Time Library routines are accessed is presented in 
OpenVMS Programming Interfaces: Calling a System Routine. A description of 
VMS features and functionality available through calls to the OTS$ Run-Time 
Library appears in the OpenVMS Programming Concepts Manual. Descriptions 
of other RTL facilities and their corresponding routines and usages are discussed 
in the following books: 

• DPML, Digital Portable Mathematics Library 

• OpenVMS RTL DECtalk (DTK$) Manual 

• OpenVMS RTL Library (LIB$) Manual 

• OpenVMS VAX RTL Mathematics (MTH$) Manual 

• OpenVMS RTL Parallel Processing (PPL$) Manual 

• OpenVMS RTL Screen Management (SMG$) Manual 

• OpenVMS RTL String Manipulation (STR$) Manual 

The Guide to DECthreads contains guidelines and reference information for 
DECthreads, the Digital Multithreading Run-Time Library. 

Application programmers using any programming language can refer to the Guide 
to Creating OpenVMS Modular Procedures for writing modular and reentrant 
code. 


v 




High-level language programmers will find additional information on calling 
Run-Time Library routines in their language reference manual. Additional 
information may also be found in the language user’s guide provided with your 
VMS language software. 

For a complete list and description of the manuals in the VMS documentation set, 
see the Overview of OpenVMS Documentation . 

Conventions 

In this manual, every use of OpenVMS AXP means the OpenVMS AXP operating 
system, every use of OpenVMS VAX means the OpenVMS VAX operating system, 
and every use of OpenVMS means both the OpenVMS AXP operating system and 
the OpenVMS VAX operating system. 

The following conventions are used to identify information specific to OpenVMS 
AXP or to OpenVMS VAX: 

The AXP icon denotes the beginning of information 
specific to OpenVMS AXP. 

The VAX icon denotes the beginning of information 
specific to OpenVMS VAX. 

The diamond symbol denotes the end of a section of 
information specific to OpenVMS AXP or to OpenVMS 
VAX. 

The following conventions are used in this manual: 

A sequence such as Ctrl/x indicates down the key labeled Ctrl 
while you press another key or a pointing device button. 

A sequence such as PF1 x indicates that you must first press 
and release the key labeled PF1, then press and release 
another key or a pointing device button. 

A sequence such as GOLD x indicates that you must first press 
and release the key defined GOLD, then press and release 
another key. GOLD key sequences can also have a slash (/), 
dash (-), or underscore (_) as a delimiter in EVE commands. 

In examples, a key name enclosed in a box indicates that 
you press a key on the keyboard. (In text, a key name is not 
enclosed in a box.) 

A horizontal ellipsis in examples indicates one of the following 
possibilities: 

• Additional optional arguments in a statement have been 
omitted. 

• The preceding item or items can be repeated one or more 
times. 

• Additional parameters, values, or other information can be 
entered. 

A vertical ellipsis indicates the omission of items from a code 
example or command format; the items are omitted because 
they are not important to the topic being discussed. 


Ctrl/jc 
PF1 x 

GOLD x 

| Return | 
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() 

[] 

{} 

boldface text 

italic text 


In format descriptions, parentheses indicate that, if you 
choose more than one option, you must enclose the choices 
in parentheses. 

In format descriptions, brackets indicate optional elements. 
You can choose one, none, or all of the options. (Brackets are 
not optional, however, in the syntax of a directory name in 
an Open VMS file specification, or in the syntax of a substring 
specification in an assignment statement.) 

In format descriptions, braces surround a required choice of 
options; you must choose one of the options listed. 

Boldface text represents the introduction of a new term or the 
name of an argument, an attribute, or a reason. 

Boldface text is also used to show user input in Bookreader 
versions of the manual. 

Italic text emphasizes important information, indicates 
variables, and indicates complete titles of manuals. Italic 
text also represents information that can vary in system 
messages (for example, Internal error number ), command lines 
(for example, /PRODUCER=^amc), and command parameters 
in text. 

Uppercase text indicates a command, the name of a routine, 
the name of a file, the name of a file protection code, or the 
abbreviation for a system privilege. 

A hyphen in code examples indicates that additional 
arguments to the request are provided on the line that follows. 

All numbers in text are assumed to be decimal, unless 
otherwise noted. Nondecimal radixes—binary, oc 
hexadecimal—are explicitly indicated. 

Other conventions used in the documentation of Run-Time Library routines are 
described in OpenVMS Programming Interfaces: Calling a System Routine. 


UPPERCASE TEXT 


numbers 
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Overview of the OTS$ Facility 


This manual discusses the Run-Time Library OTS$ routines that perform general 
purpose functions. These functions include data type conversions as part of a 
compiler’s generated code, and some mathematical functions. 

Most of the OTS$ routines were originally designed to support language 
compilers. Because they provide useful functions, they were moved into the 
language-independent facility, OTS$. 

The OTS$ facility provides you with routines that perform seven main tasks: 

• Convert data types 

• Divide complex and packed decimal values 

• Move data to a specified destination address 

• Multiply complex values 

• Raise a base to an exponent 

• Copy a source string to a destination string 

• Return a string area to free storage 

Table 1-1, Table 1-2, Table 1-3, Table 1-4, Table 1-5, Table 1-6, and Table 1-7 
contain all of the OTS$ routines grouped according to their functions. 


Table 1-1 OTS$ Conversion Routines 
Conversion Routine Function 


OTS$CNVOUT 

OTS$CVT_L_TB 

OTS$CVT_L_TI 

OTS$CVT_L_TL 

OTS$CVT_L_TO 

OTS$CVT_L_TU 

OTS$CVT_L_TZ 

OTS$CVT_TB_L 

OTS$CVT_TI_L 

OTS$CVT_TL_L 

OTS$CVT_TO_L 


Convert a D-floating, G-floating, or H-floating value to a 
character string 

Convert an unsigned integer to binary text 
Convert a signed integer to signed integer text 
Convert an integer to logical text 
Convert an unsigned integer to octal text 
Convert an unsigned integer to decimal text 
Convert an integer to hexadecimal text 
Convert binary text to an unsigned integer value 
Convert signed integer text to an integer value 
Convert logical text to an integer value 
Convert octal text to an integer value 

(continued on next page) 
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Overview of the OTS$ Facility 


Table 1-1 (Cont.) OTS$ Conversion Routines 


Conversion Routine 

Function 

OTS$CVT_TU_L 

Convert unsigned decimal text to an integer value 

OTS$CVT_T_z 

Convert numeric text to a D- or F-floating value 

OTS$CVT_T_x 

Convert numeric text to a G- or H-floating value 

OTS$CVT_TZ_L 

Convert hexadecimal text to an unsigned longword integer 
value 


For more information on Run-Time Library conversion routines, see the CVT$ 
reference section in the OpenVMS RTL Library (LIB$) Manual. 


Table 1-2 OTS$ Division Routines 

Division Routine 

Function 

OTS$DIVCx 

Perform complex division 

OTS$DIV_PK_LONG 

Perform packed decimal division with a long 
divisor 

OTS$DIV_PK_SHORT 

Perform packed decimal division with a short 
divisor 


Table 1-3 OTS$ Move Data Routines 


Move Data Routine 

Function 

OTS$MOVE3 

Move data without fill 

OTS$MOVE5 

Move data with fill 

Table 1-4 OTS$ Multiplication Routine 

Multiplication Routine 

Function 

OTS$MULCx 

Perform complex multiplication 

Table 1-5 OTS$ Exponentiation Routines 

Exponentiation Routine 

Function 


OTS$POWCxCx Raise a complex base to a complex floating¬ 

point exponent 


OTS$POWCxJ 

OTS$POWDD 


Raise a complex base to a signed longword 
exponent 

Raise a D-floating base to a D-floating 
exponent 


OTS$POWDR 

OTS$POWDJ 


Raise a D-floating base to an F-floating 
exponent 

Raise a D-floating base to a longword integer 
exponent 

(continued on next page) 
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Overview of the OTS$ Facility 


Table 1-5 (Cont.) OTS$ Exponentiation Routines 


Exponentiation Routine 

Function 

OTS$POWGx 

Raise a G-floating base to a G-floating or 
longword integer exponent 

OTS$POWGJ 

Raise a G-floating base to a longword integer 
exponent 

tOTS$POWHx 

Raise an H-floating base to a floating-point 
exponent 

OTS$POWHJ 

Raise an H-floating base to a longword integer 
exponent 

OTS$POWII 

Raise a word integer base to a word integer 
exponent 

OTS$POWHJJ 

Raise a longword integer base to a longword 
integer exponent 

OTS$POWLULU 

Raise an unsigned longword integer base to an 
unsigned longword integer exponent 

OTS$POWxLU 

Raise a floating-point base to an unsigned 
longword integer exponent 

OTS$POWRD 

Raise an F-floating base to a D-floating 
exponent 

OTS$POWRJ 

Raise an F-floating base to a longword integer 
exponent 

OTS$POWRR 

Raise an F-floating base to an F-floating 
exponent 


tVAX VMS specific. 


Table 1-6 OTS$ Copy Source String Routines 


Copy Source String Routine 

Function 

OTS$SCOPY_DXDX 

Copy a source string passed by descriptor to a 
destination string 

OTS$SCOPY_R_DX 

Copy a source string passed by reference to a 
destination string 


Table 1-7 OTS$ Return String Area Routines 


Return String Area Routine 

Function 

OTS$SFREE 1_DD 
OTS$SFREEN_DD 

OTS$SGET 1_DD 

Free one dynamic string 

Free n dynamic strings 

Get one dynamic string 
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OTS$ Reference Section 


This section provides detailed descriptions of the routines provided by the VMS 
RTL General Purpose (OTS$) Facility. 
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OTS$CNVOUT 


OTS$CNVOUT—Convert D-Floating, G-Floating or H-Floating 

Number to Character String 

The Convert Floating to Character String routines convert a D-floating, G-floating 
or H-floating number to a character string in the FORTRAN E format. 

Format 

OTS$CNVOUT D-G-or-H-float-pt-input-val ,fixed-length-resultant-string 
,digits-in-fraction 

OTS$CNVOUT_G D-G-or-H-float-pt-input-val ,fixed-length-resultant-string 
,digits-in-fraction 



OTS$CNVOUT_HD-G-or-H-float-pt-input-val ,fixed-length-resultant-string 
,digits-in-fraction ♦ 

Returns 

Open VMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 


Arguments 

D-G-or-H-float-pt-input-val 

Open VMS usage floating_point 
type D_floating, G_floating, H_floating 

access read only 

mechanism by reference 

Value that OTS$CNVOUT converts to a character string. For OTS$CNVOUT, 
the D-G-or-H-float-pt-input-val argument is the address of a D-floating number 
containing the value. For OTS$CNVOUT_G, the D-G-or-H-float-pt-input- 
val argument is the address of a G-floating number containing the value. For 
OTS$CNVOUT_H, the D-G-or-H-float-pt-input-val argument is the address of 
an H-floating number containing the value. 

fixed-length-resultant-string 

Open VMS usage char_string 
type character string 

access write only 

mechanism by descriptor, fixed length 

Output string into which OTS$CNVOUT writes the character string result of the 
conversion. The fixed-length-resultant-string argument is the address of a 
descriptor pointing to the output string. 
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OTS$CNVOUT 


digits-in-fraction 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by value 

Number of digits in the fractional portion of the result. The digits-in-fraction 
argument is an unsigned longword containing the number of digits to be written 
to the fractional portion of the result. 


Normal successful completion. 

Floating reserved operand detected. 

Output conversion error. The result would have 
exceeded the fixed-length string; the output 
string is filled with asterisks. 


Condition Values Returned 

SS$_NORMAL 

SS$_ROPRAND 

OTS$_OUTCONERR 
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OTS$CVT_LTB 


OTS$CVT_L_TB—Convert an Unsigned Integer to Binary Text 

The Convert an Unsigned Integer to Binary Text routine converts an unsigned 
integer value of arbitrary length to binary representation in an ASCII text string. 
By default, a longword is converted. 

Format 

OT S$C VT_L_TB 

Returns 

Open VMS usage 
type 
access 
mechanism 

Arguments 

varying-input-value 

Open VMS usage varying_arg 
type unspecified 

access read only 

mechanism by reference 

Unsigned byte, word, or longword that OTS$CVT_L_TB converts to an unsigned 
decimal representation in an ASCII text string. (The value of the input-value- 
size argument determines whether varying-input-value is a byte, word, or 
longword.) The varying-input-value argument is the address of the unsigned 
integer. 

fixed-length-resultant-string 

Open VMS usage char_string 
type character string 

access write only 

mechanism by descriptor, fixed-length 

ASCII text string that OTS$CVT_L_TB creates when it converts the integer 
value. The fixed-length-resultant-string argument is the address of a 
descriptor pointing to this ASCII text string. The string is assumed to be of 
fixed length (DSC$K_CLASS_S). 

number-of-digits 

Open VMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 

Minimum number of digits in the binary representation to be generated. The 
number-of-digits argument is a signed longword containing this minimum 
number. If the minimum number of digits is omitted, the default is 1. If the 
actual number of significant digits is less than the minimum number of digits, 
leading zeros are produced. If the minimum number of digits is zero and the 
value of the integer to be converted is also zero, OTS$CVT_L_TB creates a blank 
string. 


varying-input-value ,fixed-length-resultant-string [,number-of-digits] 
[,input-value-size] 


condjvalue 
longword (unsigned) 
write only 
by value 
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OTS$CVT_L_TB 


input-value-size 

OpenVMS usage 

type 

access 

mechanism 


longword_signed 
longword (signed) 
read only 
by value 


Size of the integer to be converted, in bytes. The input-value-size argument is 
a signed longword containing the byte size. This is an optional argument. If the 
size is omitted, the default is 4 (longword). 


Condition Values Returned 


Example 


SS$_NORMAL 

OTS$_OUTCONERR 


Normal successful completion. 

Output conversion error. The result would have 
exceeded the fixed-length string; the output 
string is filled with asterisks. 


0 | 1 I 2 I 3 I 4 I 5 I 6 I 7 I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

FTTY D F 4 TTY 

C* Initialize numeric value to be converted. 

C Z-ADD13 VALUE 90 

C CVTLTB EXTRN'OTS$CVT_L_TB' 

C* Convert the number to binary in a string. 

C CALL CVTLTB 

C PARM VALUE RL 

C PARMD OUTSTR 4 

C* Display the converted string on the terminal. 

C OUTSTR DSPLYTTY 

C SETON LR 

This RPG II program displays the string ' 1101' on the terminal. 
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OTS$CVT_L_TI 


OTS$CVT L TI—Convert Signed Integer to Decimal Text 

The Convert Signed Integer to Decimal Text routine converts a signed integer to a 
decimal ASCII text string. This routine supports FORTRAN Iw and Iw.m output 
and BASIC output conversion. 

Format 

OTS$CVT_L_TI varying-input-value ,fixed-length-resultant-string [,number-of-digits] 

[,input-value-size] [,flags-value] 

Returns 

Open VMS usage 
type 
access 
mechanism 

Arguments 

varying-input-value 

Open VMS usage varying_arg 
type unspecified 

access read only 

mechanism by reference 

Unsigned byte, word, or longword that OTS$CVT_L_TI converts to an unsigned 
decimal representation in an ASCII text string. (The value of the input-value- 
size argument determines whether varying-input-value is a byte, word, or 
longword.) The varying-input-value argument is the address of the unsigned 
integer. 

fixed-length-resultant-string 

Open VMS usage char_string 
type character string 

access write only 

mechanism by descriptor, fixed length 

Decimal ASCII text string that OTS$CVT_L_TI creates when it converts the 
signed integer. The fixed-length-resultant-string argument is the address of a 
descriptor pointing to this text string. The string is assumed to be of fixed length 
(DSC$K_CLASS_S). 

number-of-digits 

Open VMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 

Minimum number of digits to be generated when OTS$CVT_L_TI converts the 
signed integer to a decimal ASCII text string. The number-of-digits argument 
is a signed longword containing this number. If the minimum number of digits 
is omitted, the default value is 1. If the actual number of significant digits is 
smaller, OTS$CVT_L_TI inserts leading zeros into the output string. If number- 
of-digits is zero and varying-input-value is zero, OTS$CVT_L_TI writes a 
blank string to the output string. 


cond_value 
longword (unsigned) 
write only 
by value 
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OTS$CVT_L_TI 


input-value-size 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 

Size of the integer to be converted, in bytes. The input-value-size argument is 
a signed longword containing this value size. The value size must be either 1, 

2, or 4. If value size is 1 or 2, the value is sign-extended to a longword before 
conversion. If the size is omitted, the default is 4 (longword). 

flags-value 

OpenVMS usage mask_longword 
type longword (unsigned) 

access read only 

mechanism by value 

Caller-supplied flags that you can use if you want OTS$CVT_L_TI to insert a 
plus sign before the converted number. The flags-value argument is an unsigned 
longword containing the flags. 

The caller flags are defined as follows: 

Bit 0 If set, a plus sign (+) is inserted before the first nonblank character in 
the output string; otherwise, the plus sign is omitted. 

If flags-value is omitted, all bits are clear and the plus sign is not inserted. 

Condition Values Returned 

SS$_NORMAL Normal successful completion. 

OTS$_OUTCONERR Output conversion error. The result would have 

exceeded the fixed-length string; the output 
string is filled with asterisks. 


OTS-8 



OTS$CVT_L_TL 


OTS$CVT_L_TL—Convert Integer to Logical Text 

The Convert Integer to Logical Text routine converts an integer to an ASCII text 
string representation using FORTRAN L (logical) format. 


Format 


Returns 


OTS$CVT_L_TL longword-integer-value ,fixed-length-resultant-string 


Open VMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 

longword-integer-value 

Open VMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by reference 

Value that OTS$CVT_L_TL converts to an ASCII text string. The longword- 
integer-value argument is the address of a signed longword containing this 
integer value. 


fixed-length-resultant-string 

Open VMS usage char_string 
type character string 

access write only 

mechanism by descriptor, fixed length 

Output string that OTS$CVT_L_TL creates when it converts the integer value 
to an ASCII text string. The fixed-length-resultant-string argument is the 
address of a descriptor pointing to this ASCII text string. 

The output string is assumed to be of fixed length (DSC$K_CLASS_S). 

If length equals the fixed length of the output string, then the output string 
consists of (length - 1) blanks followed by the letter T if bit 0 is set, or the letter 
F if bit 0 is clear. 


Condition Values Returned 


SS$_NORMAL Normal successful completion. 

OTS$_OUTCONERR Output conversion error. The result would have 

exceeded the fixed-length string; the output 
string is of zero length (DSC$W_LENGTH= 0). 
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OTS$CVT_L_TL 


Example 


5 ! + 

! This is an example program 
! showing the use of OTS$CVT_L_TL. 

VALUE% =10 
OUTSTR$ = ' ' 

CALL OTS$CVT_L_TL(VALUE!, OUTSTR$) 

PRINT 0UTSTR$ 

9 END 

This BASIC example illustrates the use of OTS$CVT_L_TL. The output generated 
by this program is ' F'. 
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OTS$CVT_L_TO 


OTS$CVT_L_TO—Convert Unsigned Integer to Octal Text 


The Convert Unsigned Integer to Octal Text routine converts an unsigned integer 
to an octal ASCII text string. OTS$CVT_L_TO supports FORTRAN Ow and 
Ow.m output conversion formats. 


Format 


Returns 


OTS$CVT_L_TO varying-input-value ,fixed-length-resultant-string [,number-of-digits] 
[,input-value-size] 


Open VMS usage 

type 

access 

mechanism 


condjvalue 
longword (unsigned) 
write only 
by value 


Arguments 


varying-input-value 

Open VMS usage varying_arg 
type unspecified 

access read only 

mechanism by reference 

Unsigned byte, word, or longword that OTS$CVT_L_TO converts to an unsigned 
decimal representation in an ASCII text string. (The value of the input-value- 
size argument determines whether varying-input-value is a byte, word, or 
longword.) The varying-input-value argument is the address of the unsigned 
integer. 


fixed-length-resultant-string 

Open VMS usage char_string 
type character string 

access write only 

mechanism by descriptor, fixed length 

Output string that OTS$CVT_L_TO creates when it converts the integer value 
to an octal ASCII text string. The fixed-length-resultant-string arg um ent is 
the address of a descriptor pointing to the octal ASCII text string. The string is 
assumed to be of fixed length (DSC$K_CLASS_S). 

number-of-digits 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 

Minimum number of digits that OTS$CVT_L_TO generates when it converts the 
integer value to an octal ASCII text string. The number-of-digits argument 
is a signed longword containing the minimum number of digits. If it is omitted, 
the default is 1. If the actual number of significant digits in the octal ASCII 
text string is less than the minimum number of digits, OTS$CVT_L_TO inserts 
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leading zeros into the output string. If number-of-digits is zero and varying- 
input-value is zero, OTS$CVT_L_TO writes a blank string to the output 
string. 

input-value-size 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 

Size of the integer to be converted, in bytes. The input-value-size argument is a 
signed longword containing the number of bytes in the integer to be converted by 
OTS$CVT_L_TO. If it is omitted, the default is 4 (longword). 


Condition Values Returned 


SS$_NORMAL 

OTS$_OUTCONERR 


Normal successful completion. 

Output conversion error. The result would have 
exceeded the fixed-length string; the output 
string is filled with asterisks. 
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OTS$CVT_L_TU—Convert Unsigned Integer to Decimal Text 

The Convert Unsigned Integer to Decimal Text routine converts a byte, word, or 
longword value to unsigned decimal representation in an ASCII text string. By 
default, a longword is converted. 

Format 

OTS$CVT_L_TU 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

varying-input-value 

OpenVMS usage varying_arg 
type unspecified 

access read only 

mechanism by reference 

Unsigned byte, word, or longword that OTS$CVT_L_TU converts to an unsigned 
decimal representation in an ASCII text string. (The value of the input-value- 
size argument determines whether varying-input-value is a byte, word, or 
longword.) The varying-input-value argument is the address of the unsigned 
integer. 

fixed-length-resultant-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor, fixed-length 

Output string (fixed-length) that OTS$CVT_L_TU creates when it converts the 
integer value to unsigned decimal representation in an ASCII text string. The 
fixed-length-resultant-string argument is the address of a descriptor pointing 
to this ASCII text string. 

number-of-digits 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 

Minimum number of digits in the ASCII text string that OTS$CVT_L_TU creates. 
The number-of-digits argument is a signed longword containing the minimum 
number. If the minimum number of digits is omitted, the default is 1. 


varying-input-value ,fixed-length-resultant-string [,number-of-digits] 
[,input-value-size] 


cond_value 
longword (unsigned) 
write only 
by value 
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If the actual number of significant digits in the output string created is less than 
the minimum number, OTS$CVT_L_TU inserts leading zeros into the output 
string. If the minimum number of digits is zero and the integer value to be 
converted is also zero, OTS$CVT_L_TU writes a blank string to the output string. 

input-value-size 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 

Size of the integer value to be converted, in bytes. The input-value-size 
argument is a signed longword containing the size of the integer value. If the size 
is omitted, the default is 4. The only values that OTS$CVT_L_TU allows are 1, 

2 and 4. If any other value is specified, OTS$CVT_L_TU uses the default value, 
which is 4 (longword). 

Condition Values Returned 

SS$_NORMAL Normal successful completion. 

OTS$_OUTCONERR Output conversion error. The result would have 

exceeded the fixed-length string; the output 
string is filled with asterisks. 

Example 

0 1 1 1 2 I 3 I 4 I 5 I 6 I 7 I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 
FTTY D F 7 TTY 

C* Initialize numeric value to be converted. 

C Z-ADD32857 VALUE 90 

C Z-ADD7 DIGITS 90 

C CVTLTU EXTRN'OTS$CVT_L_TU' 

C* Convert the number to decimal in a string with 7 decimal digits. 

C CALL CVTLTU 

C PARM VALUE RL 

C PARMD OUTSTR 7 

C PARMV DIGITS 

C* Display the converted string on the terminal. 

C OUTSTR DSPLYTTY 

C SETON LR 

This RPG II program displays the string ' 0032857' on the terminal screen. 
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OTS$CVT_L_TZ—Convert Integer to Hexadecimal Text 


The Convert Integer to Hexadecimal Text routine converts an unsigned integer to 
a hexadecimal ASCII text string. OTS$CVT_L_TZ supports FORTRAN Zw and 
Zw.m output conversion formats. 


Format 


Returns 


OTS$CVT_L_TZ varying-input-value ,fixed-length-resultant-string [,number-of-digits] 
[,input-value-size] 


Open VMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


varying-input-value 

OpenVMS usage varying_arg 
type unspecified 

access read only 

mechanism by reference 

Unsigned byte, word, or longword that OTS$CVT_L_TZ converts to an unsigned 
decimal representation in an ASCII text string. (The value of the input-value- 
size argument determines whether varying-input-value is a byte, word, or 
longword.) The varying-input-value argument is the address of the unsigned 
integer. 


fixed-length-resultant-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor, fixed length 

Output string that OTS$CVT_L_TZ creates when it converts the integer value to 
a hexadecimal ASCII text string. The fixed-length-resultant-string argument 
is the address of a descriptor pointing to this ASCII text string. The string is 
assumed to be of fixed length (DSC$K_CLASS_S). 


number-of-digits 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 

Minimum number of digits in the ASCII text string that OTS$CVT_L_TZ creates 
when it converts the integer. The number-of-digits argument is a signed 
longword containing this minimum number. If it is omitted, the default is 1. If 
the actual number of significant digits in the text string that OTS$CVT_L_TZ 
creates is less than this minimum number, OTS$CVT_L_TZ inserts leading zeros 
in the output string. If the minimum number of digits is zero and the integer 
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value to be converted is also zero, OTS$CVT_L_TZ writes a blank string to the 
output string. 

input-value-size 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 

Size of the integer that OTS$CVT_L_TZ converts, in bytes. The input-value-size 
argument is a signed longword containing the value size. If the size is omitted, 
the default is 4 (longword). 

Condition Values Returned 

SS$_NORMAL 
OTS$_OUTCONERR 


Example 

with TEXT_IO; use TEXT_IO; 
procedure SHOW_CONVERT is 

type INPUT_INT is new INTEGER range 0..INTEGER'LAST; 

INTVALUE : INPUT_INT := 256; 

HEXSTRING : STRING(1..11); 

procedure CONVERT_TO_HEX (I : in INPUT_INT; HS : out STRING); 

pragma INTERFACE (RTL, C0NVERT_T0_HEX); 

pragma IMPORT_routine (INTERNAL => CONVERT_TO_HEX, 

EXTERNAL => "OTS$CVT_L_TZ", 

MECHANISM =>(REFERENCE, 

DESCRIPTOR (CLASS => S))) ; 

begin 

CONVERT_TO_HEX (INTVALUE, HEXSTRING); 

PUT_LINE("This is the value of HEXSTRING"); 

PUT_LINE(HEXSTRING); 
end; 

This VAX Ada example uses OTS$CVT_L_TZ to convert a longword integer to 
hexadecimal text. 


Normal successful completion. 

Output conversion error. The result would have 
exceeded the fixed-length string; the output 
string is filled with asterisks. 
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OTS$CVT_TB_L—Convert Binary Text to Unsigned Integer 

The Convert Binary Text to Unsigned Integer routine converts an ASCII text 
string representation of an unsigned binary value to an unsigned integer value of 
arbitrary length. By default, the result is a longword. Valid input characters are 
the blank and the digits 0 and 1. No sign is permitted. 

Format 

OTS$CVT_TB_L input-string ,varying-output-value [,output-value-size] [,flags-value] 


Returns 


Open VMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


input-string 

Open VMS usage 

type 

access 

mechanism 


char_string 
character string 
read only 
by descriptor 


Input string containing the string representation of an unsigned binary value 
that OTS$CVT_TB_L converts to an integer value. The input-string argument 
is the address of a descriptor pointing to the string. 


varying-output-value 

OpenVMS usage varying_arg 
type unspecified 

access write only 

mechanism by reference 

Unsigned byte, word, or longword that OTS$CVT_TB_L creates when it converts 
the ASCII text string. (The value of the output-value-size argument determines 
whether varying-output-value is a byte, word, or longword.) The varying- 
output-value argument is the address of the unsigned integer. 

output-value-size 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 


Number of bytes to be occupied by the value created when OTS$CVT_TB_L 
converts the ASCII text string to an integer value. The output-value-size 
argument contains the value size. If output-value-size contains a zero or a 
negative number, OTS$CVT_TB_L returns an error code as the condition value. 
Valid values for the output-value-size argument are 1, 2, and 4; the contents 
determine whether the integer value that OTS$CVT_TB_L creates is a byte, 
word, or longword. If the number of bytes is omitted, the default is 4 (longword). 
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flags-value 

OpenVMS usage 

type 

access 

mechanism 


mask_longword 
longword (unsigned) 
read only 
by value 


User-supplied flags that OTS$CVT_TB_L uses to determine how to interpret 
blanks and tabs. The flags-value argument contains the value of the user- 
supplied flags. 

The flags are defined as follows: 


Bit Description _ 

0 If set, OTS$CVT_TB_L ignores blanks. If clear, OTS$CVT_TB_L 

interprets blanks as zeros. 

4 If set, OTS$CVT_TB_L ignores tabs. If clear, OTS$CVT_TB_L 

interprets tabs as invalid characters. 


The default is that all bits are clear. 

Condition Values Returned 

SS$_NORMAL Normal successful completion. 

OTS$_INPCONERR Input conversion error. An invalid character, 

overflow, or invalid input-value-size occurred. 

Example 

OPTION & 

TYPE = EXPLICIT 

! + 

! This program demonstrates the use of OTS$CVT_TB_L from BASIC. 

! Several binary numbers are read and then converted to their 
! integer equivalents. 

! + 

! DECLARATIONS 

DECLARE STRING BIN_STR 

DECLARE LONG BIN.VAL, I, RET_STATUS 

DECLARE LONG CONSTANT FLAGS =17 !2 A 0+2 A 4 

EXTERNAL LONG FUNCTION OTS$CVT_TB_L (STRING, LONG, & 

LONG BY VALUE, LONG BY VALUE) 

! + 

! MAIN PROGRAM 


+ 

Read the data, convert it to binary, and print the result. 
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FOR I = 1 TO 5 
READ BIN_STR 

RET_STATUS = OTS$CVT_TB_L( BIN_STR, BIN_VAL, '4'L, FLAGS) 

PRINT BIN_STR; 11 treated as a binary number equals";BIN VAL 
NEXT I 

! + 

! Done, end the program. 

GOTO 32767 

999 Data "1111", "1 111", "1011011", "11111111", ”00000000" 

32767 END 

This BASIC example program demonstrates how to call OTS$CVT_TB_L to 
convert binary text to a longword integer. 

The output generated by this BASIC program is as follows: 

1111 treated as a binary number equals 15 
1 111 treated as a binary number equals 15 
1011011 treated as a binary number equals 91 
11111111 treated as a binary number equals 255 
00000000 treated as a binary number equals 0 
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OTS$CVT_TI_L—Convert Signed Integer Text to Integer 

The Convert Signed Integer Text to Integer routine converts an ASCII text string 
representation of a decimal number to a signed byte, word, or longword integer 
value. The result is a longword by default, but the calling program can specify a 
byte or a word value instead. 


Format 

OTS$CVT_TLL fixed-or-dynamic-input-string ,varying-output-value 
[,output-value-size] [,flags-value] 

Returns 

OpenVMS usage condjvalue 
type longword (unsigned) 

access write only 

mechanism by value 

Arguments 

fixed-or-dynamic-input-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor, fixed-length or dynamic string 

Input ASCII text string that OTS$CVT_TI_L converts to a signed byte, word, 
or longword. The fixed-or-dynamic-input-string argument is the address of a 
descriptor pointing to the input string. 

The syntax of a valid ASCII text input string is as follows: 

[+ or -] <integer-digits> 

OTS$CVT_TI_L always ignores leading blanks. A decimal point is assumed at 
the right of the input string. 

varying-output-value 

OpenVMS usage varying_arg 
type unspecified 

access write only 

mechanism by reference 

Unsigned byte, word, or longword that OTS$CVT_TI_L creates when it converts 
the ASCII text string. (The value of the output-value-size argument determines 
whether varying-output-value is a byte, word, or longword.) The varying- 
output-value argument is the address of the unsigned integer. 

output-value-size 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 

Number of bytes to be occupied by the value created when OTS$CVT_TI_L 
converts the ASCII text string to an integer value. The output-value-size 
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argument contains the number of bytes. If output-value-size contains a zero or 
a negative number, OTS$CVT_TI_L returns an error code as the condition value. 
Valid values for the output-value-size argument are 1, 2, and 4; the contents 
determine whether the integer value that OTS$CVT_TI_L creates is a byte, word, 
or longword. If the number of bytes is omitted, the default is 4 (longword). 

flags-value 

Open VMS usage mask_longword 
type longword (unsigned) 

access read only 

mechanism by value 

User-supplied flags that OTS$CVT_TI_L uses to determine how blanks and tabs 
are interpreted. The flags-value argument is an unsigned longword containing 
the value of the flags. 


Bit Description 

0 If set, OTS$CVT_TI_L ignores all blanks. If clear, OTS$CVT_TI_ 

L ignores leading blanks but interprets blanks after the first legal 
character as zeros. 

4 If set, OTS$CVT_TI_L ignores tabs. If clear, OTS$CVT_TI_L interprets 

tabs as invalid characters. 


If flags-value is omitted, the default is that all bits are cleared. 

Condition Values Returned 

SS$_NORMAL Normal successful completion. 

OTS$_INPCONERR Input conversion error: an invalid character in 

the input string; or the value overflows byte, 
word, or longword; or output-value-size is 
invalid. Varying-output-value is set to zero. 
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OTS$CVT_TL_L—Convert Logical Text to Integer 

The Convert Logical Text to Integer routine converts an ASCII text string 
representation of a FORTRAN-77 L format to a byte, word, or longword integer 
value. The result is a longword by default, but the calling program can specify a 
byte or a word value instead. 

Format 

OTS$CVT_TL_L 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

fixed-or-dynamic-input-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor, fixed-length or dynamic string 

Input string containing an ASCII text representation of a FORTRAN-77 L format 
that OTS$CVT_TL_L converts to a byte, word, or longword integer value. The 
fixed-or-dynamic-input-string argument is the address of a descriptor pointing 
to the input string. 

The syntax of a valid ASCII text input string is either: Blank (end of string) or 
Blank Period Letter Character (end of string) 

The elements in the preceding input string are defined as follows: 


fixed-or-dynamic-input-string ,varying-output-value 
[.output-value-size] 


cond_value 
longword (unsigned) 
write only 
by value 


Term 

Description 

Blank 

Zero or more blanks 

Period 

. or nothing 

Letter 

T, t, F, or f 

Character 

Zero or more of any character 

varying-output-value 

OpenVMS usage 

varying_arg 

type 

unspecified 

access 

write only 

mechanism 

by reference 


Unsigned byte, word, or longword that OTS$CVT_TL_L creates when it converts 
the ASCII text string. (The value of the output-value-size argument determines 
whether varying-output-value is a byte, word, or longword.) The varying- 
output-value argument is the address of the unsigned integer. 


OTS-22 







OTS$CVT_TL_L 


OTS$CVT_TL_L returns -1 as the contents of the varying-output-value 
argument if the character denoted by “Letter” is “T” or “t”. Otherwise, OTS$CVT_ 
TL_L sets varying-output-value to zero. 

output-value-size 

Open VMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 

Number of bytes to be occupied by the value created when OTS$CVT_TL_L 
converts the ASCII text string to an integer value. The output-value-size 
argument contains the number of bytes. If output-value-size contains a zero or 
a negative number, OTS$CVT_TL_L returns an error code as the condition value. 
Valid values for the output-value-size argument are 1, 2, and 4; the contents 
determine whether the integer value that OTS$CVT_TI_L creates is a byte, word, 
or longword. If it is omitted, the default is 4 (longword). 


Condition Values Returned 


SS$_NORMAL 

OTS$_INPCONERR 


Normal successful completion. 

Invalid character in the input string or invalid 

input-value-size; varying-input-value is set 

to zero. 
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OTS$CVT_TO_L—Convert Octal Text to Signed Integer 

The Convert Octal Text to Signed Integer routine converts an ASCII text string 
representation of an octal value to a signed integer of an arbitrary length. The 
result is a longword by default, but the calling program can specify a byte, word, 
or longword. 

Format 

OT S$C VT_T 0_L 

Returns 

OpenVMS usage 
type 
access 
mechanism 


fixed-or-dynamic-input-string ,varying-output-value 
[,output-value-size] [,flags-value] 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 

fixed-or-dynamic-input-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor, fixed-length or dynamic string 

Input string containing an ASCII text string representation of an octal value that 
OTS$CVT_TO_L converts to a signed integer. The fixed-or-dynamic-input- 
string argument is the address of a descriptor pointing to the input string. The 
valid input characters are blanks and the digits are 0 through 7. No sign is 
permitted. 

varying-output-value 

OpenVMS usage varying_arg 
type unspecified 

access write only 

mechanism by reference 

Signed byte, word, or longword that OTS$CVT_TO_L creates when it converts 
the ASCII text string. (The value of the output-value-size argument determines 
whether varying-output-value is a byte, word, or longword.) The varying- 
output-value argument is the address of the signed integer. 

output-value-size 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by value 

Number of bytes occupied by the signed integer value. The output-value-size 
argument contains the number of bytes. If the content of the output-value-size 
argument is zero or a negative number, OTS$CVT_TO_L returns an error. If the 
number of bytes is omitted, the default is 4 (longword). 
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flags-value 

Open VMS usage 

type 

access 

mechanism 


mask_longword 
longword (unsigned) 
read only 
by value 


User-supplied flags that OTS$CVT_TO_L uses to determine how blanks within 
the input string are interpreted. The flags-value argument contains the user- 
supplied flags. 

Bit 0 If set, OTS$CVT_TO_L ignores all blanks. If clear, OTS$CVT_TO_L 
interprets blanks as zeros. 

If flags-value is omitted, the default is that all bits are clear. 


Condition Values Returned 

SS$_NORMAL Normal successful completion. 

OTS$_INPCONERR Input conversion error. An invalid character, 

overflow, or invalid input-value-size occurred. 

Example 

0CTAL_C0NV: PROCEDURE OPTIONS (MAIN) RETURNS (FIXED BINARY (31)); 


%INCLUDE $STSDEF; /* Include definition of return status values */ 

DECLARE 0TS$CVT_T0_L ENTRY 

(CHARACTER (*), /* Input string passed by descriptor */ 

FIXED BINARY (31), /* Returned value passed by reference */ 

FIXED BINARY VALUE, /* Size for returned value passed by value */ 

FIXED BINARY VALUE) /* Flags passed by value */ 

RETURNS (FIXED BINARY (31)) /* Return status */ 

OPTIONS (VARIABLE); /* Arguments may be omitted */ 

DECLARE INPUT CHARACTER (10); 

DECLARE VALUE FIXED BINARY (31); 

DECLARE SIZE FIXED BINARY(31) INITIAL(4) READONLY STATIC; /* Longword */ 

DECLARE FLAGS FIXED BINARY(31) INITIAL(1) READONLY STATIC; /* Ignore blanks */ 

ON ENDFILE (SYSIN) STOP; 


DO WHILE (' 1' B); /* Loop continuously, until end of file */ 

PUT SKIP (2); 

GET LIST (INPUT) OPTIONS (PROMPT ('Octal value: ')); 

STS$VALUE = OTS$CVT_TO_L (INPUT, VALUE, SIZE, FLAGS); 

IF A STS$SUCCESS THEN RETURN (STS$VALUE); 

PUT SKIP EDIT (INPUT, 'Octal equals', VALUE, 'Decimal') 

(A,X,A,X,F(10),X,A); 

END; 

END OCTAL_CONV; 

This PL/I program translates an octal value in ASCII into a fixed binary value. 
The program is run interactively; simply press Ctrl/Z to quit. 

$ RUN OCTAL 
Octal value: 1 

I Octal equals 1 Decimal 
Octal value: 11 

II Octal equals 9 Decimal 
Octal value: 1017346 

1017346 Octal equals 274150 Decimal 
Octal value: Ctrl/Z 


OTS-25 








OTS$CVT_TU_L 


OTS$CVT_TU_L—Convert Unsigned Decimal Text to Integer 

The Convert Unsigned Decimal Text to Integer routine converts an ASCII text 
string representation of an unsigned decimal value to an unsigned byte, word, or 
longword value. By default, the result is a longword. Valid input characters are 
the space and the digits 0 through 9. No sign is permitted. 

Format 

OTS$CVT_TU_L fixed-length-input-string ,varying-output-value [,output-value-size] 
[,flags-value] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

fixed-length-input-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor, fixed-length 

Input string (fixed-length) containing an ASCII text string representation of 
an unsigned decimal value that OTS$CVT_TU_L converts to a byte, word, or 
longword value. The fixed-length-input-string argument is the address of a 
descriptor pointing to the input string. 

varying-output-value 

OpenVMS usage varying_arg 
type unspecified 

access write only 

mechanism by reference 

Unsigned byte, word, or longword that OTS$CVT_TU_L creates when it converts 
the ASCII text string. (The value of the output-value-size argument determines 
whether varying-output-value is a byte, word, or longword.) The varying- 
output-value argument is the address of the unsigned integer. 

output-value-size 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by value 

Number of bytes occupied by the value created when OTS$CVT_TU_L converts 
the input string. The output-value-size argument contains the number of bytes. 
OTS$CVT_TU_L allows value sizes of 1, 2 and 4. If any other value is specified, 
or if output-value-size is omitted, OTS$CVT_TU_L uses the default, which is 4. 


cond_value 
longword (unsigned) 
write only 
by value 
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flags-value 

Open VMS usage mask_longword 


type 

longword (unsigned) 

access 

read only 

mechanism by value 

User-supplied flags that OTS$CVT_TU_L uses to determine how blanks and tabs 
are interpreted. The flags-value argument contains the user-supplied flags. 

Bit 

Description 

0 

If set, OTS$CVT_TU_L ignores blanks. If clear, OTS$CVT_TU_L 
interprets blanks as zeros. 

4 

If set, OTS$CVT_TU_L ignores tabs. If clear, OTS$CVT_TU_L interprets 
tabs as invalid characters. 


If it is omitted, the default is that all bits are clear. 


Condition Values Returned 

SS$_NORMAL Normal successful completion. 

OTS$_INPCONERR Input conversion error. An invalid character, 

overflow or invalid input-value-size occurred. 


OTS-27 









OTS$CVT_T_z 


OTS$CVT 


Format 


Returns 


Arguments 


T_z—Convert Numeric Text to D- or F-Floating Value 

The Convert Numeric Text to D- or F-Floating routines convert an ASCII text 
string representation of a numeric value to a D-floating or F-floating value. 


OTS$CVT_T_D fixed-or-dynamic-input-string .floating-point-value [,digits-in-fraction] 
[.scale-factor] [.flags-value] [.extension-bits] 

OTS$CVT_T_F fixed-or-dynamic-input-string .floating-point-value [,digits-in-fraction] 
[.scale-factor] [,flags-value] [.extension-bits] 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 


fixed-or-dynamic-input-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor, fixed-length or dynamic string 

Input string containing an ASCII text string representation of a numeric value 
that OTS$CVT_T_z converts to a D-floating or F-floating value. The fixed-or- 
dynamic-input-string argument is the address of a descriptor pointing to the 
input string. 

The syntax of a valid input string is as follows: 

Blank Sign Digit Period Digit letter blank si ° n OR si ° n 

The elements in the preceding input string are defined as follows: 


Term 

Description 

Blank 

Zero or more blanks 

Sign 

or nothing 

Digit 

Zero or more decimal digits 

Period 

. or nothing 

Letter 

E, e, D, d, Q, or q 

There is no difference in semantics among any of the six valid exponent letters 
(E, e, D, d, Q, q). 

floating-point-value 

OpenVMS usage 

floating_point 

type 

D_floating, F_floating 

access 

write only 

mechanism 

by reference 
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Floating-point value that OTS$CVT_T_z creates when it converts the input 
string. The floating-point-value argument is the address of the floating-point 
value. For OTS$CVT_T_D, floating-point-value is a D-floating number. For 
OTS$CVT_T_F, floating-point-value is an F-floating number. 


digits-in-fraction 

Open VMS usage 

type 

access 

mechanism 


longword_unsigned 
longword (unsigned) 
read only 
by value 


Number of digits in the fraction if no decimal point is included in the input string. 
The digits-in-fraction argument contains the number of digits. If the number of 
digits is omitted, the default is zero. 


scale-factor 

Open VMS usage 

type 

access 

mechanism 


longword_signed 
longword (signed) 
read only 
by value 


Scale factor. The scale-factor argument contains the value of the scale factor. 
If bit 6 of the flags-value argument is clear, the resultant value is divided by 
10 scale—factor un i ess the exponent is present. If bit 6 of flags-value is set, the 
scale factor is always applied. If the scale factor is omitted, the default is zero. 

flags-value 

Open VMS usage mask_longword 
type longword (unsigned) 

access read only 

mechanism by value 


User-supplied flags. The flags-value argument contains the user-supplied flags. 

Bit 0 If set, OTS$CVT_T_z ignores blanks. If clear, OTS$CVT_T_z 
interprets blanks as zeros. 

Bit 1 If set, OTS$CVT_T_z allows only E or e exponents. If clear, 

OTS$CVT_T_z allows E, e, D, d, Q and q exponents. (Bit 1 is clear for 
BASIC and set for FORTRAN.) 

Bit 2 If set, OTS$CVT_T_z interprets an underflow as an error. If clear, 
OTS$CVT_T_z does not interpret an underflow as an error. 

Bit 3 If set, OTS$CVT_T_z truncates the value. If clear, OTS$CVT_T-z 
rounds the value. 

Bit 4 If set, OTS$CVT_T_z ignores tabs. If clear, OTS$CVT_T_z interprets 
tabs as invalid characters. 

Bit 5 If set, an exponent must begin with a valid exponent letter. If clear, 
the exponent letter can be omitted. 

Bit 6 If set, OTS$CVT_T_z always applies the scale factor. If clear, 

OTS$CVT_T_z applies the scale factor only if there is no exponent 
present in the string. 

If flags-value is omitted, all bits are clear. 
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extension-bits 

OpenVMS usage 

type 

access 

mechanism 


word_signed 
word (signed) 
write only 
by reference 


Extra precision bits. The extension-bits argument is the address of a word . 
containing the extra precision bits. If extension-bits is present, floating-point- 
value is not rounded, and the first n bits after truncation are returned in this 


argument. 


These values are suitable for use as the extension operand in an EMOD 
instruction. 


Description 

These routines support FORTRAN D, E, F, and G input type conversion as well 
as similar types for other languages. 

OTS$CVT_T_D and OTS$CVT_T_F provide run-time support for BASIC and 
FORTRAN input statements. 


Condition Values Returned 

SS$_NORMAL 

OTS$_INPCONERR 


Normal successful completion. 

Input conversion error; an invalid character in 
the input string, or the value is outside the range 
that can be represented. Floating-point-value 
is set to +0.0 (not reserved operand -0.0). 


Example 

c+ 

C This is a FORTRAN program demonstrating the use of 
C 0TS$CVT_T_F. 

C- 

REAL*4 A 

CHARACTER* 10 T(5) 

DATA T/'1234567+23','8.786534+3','-983476E-3','-23.734532','45'/ 
DO 2 I = 1, 5 
TYPE 1,I,T(I) 

1 FORMAT(' Input string ',11,' is ',A10) 

c+ 

C B is the return status. 

C T(I) is the string to be converted to an 
C F-floating point value. A is the F-floating 
C point conversion of T(I). %VAL(5) means 5 digits 

C are in the fraction if no decimal point is in 
C the input string T(I). 

C- 

B = OTS$CVT_T_F(T(I),A,%VAL(5),,) 

TYPE Output of 0TSCVT_T_F is ' ,A 
TYPE *,' ' 

2 CONTINUE 
END 
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This FORTRAN example demonstrates the use of OTS$CVT_T_F. The output 
generated by this program is as follows: 


Input string 1 is 1234567+23 
Output of OTSCVT_T_F is 
Input string 2 is 8.786534+3 
Output of 0TSCVT_T_F is 
Input string 3 is -983476E-3 
Output of 0TSCVT_T_F is 
Input string 4 is -23.734532 
Output of 0TSCVT_T_F is 
Input string 5 is 45 
Output of OTSCVT_T_F is 


1.2345669E+24 

8786.534 

-9.8347599E-03 

-23.73453 

45000.00 
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OTS$CVT_T_z—Convert Numeric Text to G- or H-Floating Value 

The Convert Numeric Text to G- or H-Floating routines convert an ASCII text 
string representation of a numeric value to a G-floating or H-floating value. 


Format 

OTS$CVT_T_G 

fixed-or-dynamic-input-string .floating-point-value [,digits-in-fraction] 


OTS$CVTT_H 

[.scale-factor] [.flags-value] [.extension-bits] 

fixed-or-dynamic-input-string .floating-point-value [,digits-in-fraction] 
[.scale-factor] [,flags-value] [.extension-bits] ♦ 

Returns 

OpenVMS usage 

condjvalue 


type 

longword (unsigned) 


access 

write only 


mechanism 

by value 


Arguments 

fixed-or-dynamic-input-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor, fixed-length or dynamic string 

Input string containing an ASCII text string representation of a numeric value 
that OTS$CVT_T_z converts to a G-floating or H-floating value. The fixed-or- 
dynamic-input-string argument is the address of a descriptor pointing to the 
input string. 

The syntax of a valid input string is as follows: 

Blank Sign Digit Period Digit letter blank sign OR sign digit 

The elements in the preceding input string are defined as follows: 


Term 

Description 

Blank 

Zero or more blanks 

Sign 

+, or nothing 

Digit 

Zero or more decimal digits 

Period 

. or nothing 

Letter 

E, e, D, d, Q, or q 


There is no difference in semantics among any of the six valid exponent letters 
(E, e, D, d, Q, q). 


floating-point-value 

OpenVMS usage 

floating_point 

type 

G_floating, H_floating 

access 

write only 

mechanism 

by reference 
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Floating-point value that OTS$CVT_T_z creates when it converts the input 
string. The floating-point-value argument is the address of the floating-point 
value. For OTS$CVT_T_G, floating-point-value is a G-floating number. For 
OTS$CVT_T_H, floating-point-value is an H-floating number. 


digits-in-fraction 

Open VMS usage 

type 

access 

mechanism 


longword_unsigned 
longword (unsigned) 
read only 
by value 


Number of digits in the fraction if no decimal point is included in the input string. 
The digits-in-fraction argument contains the number of digits. If the number of 
digits is omitted, the default is zero. 


scale-factor 

Open VMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 

Scale factor. The scale-factor argument contains the value of the scale factor. 
If bit 6 of the flags-value argument is clear, the resultant value is divided by 
jQscale-factor un i ess the exponent is present. If bit 6 of flags-value is set, the 
scale factor is always applied. If the scale factor is omitted, the default is zero. 

flags-value 

Open VMS usage mask_longword 
type longword (unsigned) 

access read only 

mechanism by value 


User-supplied flags. The flags-value argument contains the user-supplied flags. 


Bit 0 
Bit 1 

Bit 2 
Bit 3 
Bit 4 
Bit 5 
Bit 6 


If set, OTS$CVT_T_z ignores blanks. If clear, OTS$CVT_T_z 
interprets blanks as zeros. 

If set, OTS$CVT_T_z allows only E or e exponents. If clear, 
OTS$CVT_T_z allows E, e, D, d, Q, and q exponents. (Bit 1 is clear 
for BASIC and set for FORTRAN.) 

If set, OTS$CVT_T_z interprets an underflow as an error. If clear, 
OTS$CVT_T_z does not interpret an underflow as an error. 

If set, OTS$CVT_T_z truncates the value. If clear, OTS$CVT_T-z 
rounds the value. 

If set, OTS$CVT_T_z ignores tabs. If clear, OTS$CVT_T_z interprets 
tabs as invalid characters. 

If set, an exponent must begin with a valid exponent letter. If clear, 
the exponent letter may be omitted. 

If set, OTS$CVT_T_z always applies the scale factor. If clear, 
OTS$CVT_T_z applies the scale factor only if there is no exponent 
present in the string. 


If flags-value is omitted, all bits are clear. 
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extension-bits 

OpenVMS usage word_signed 


type 


access 

mechanism 


word (signed) 
write only 
by reference 


Extra precision bits. The extension-bits argument is the address of a signed 
word integer containing the extra precision bits. If present, floating-point-value 
is not rounded, and the first n bits after truncation are returned in this argument. 
For G-floating and H-floating, n equals 11 and 15, respectively, and the bits are 
returned as a word, left-justified. 

These values are suitable for use as the extension operand in an EMOD 
instruction. 

The extra precision bits returned for H-floating may not be precise because 
calculations are only carried to 128 bits. However, the error should be small. 


Description 


These routines support FORTRAN D, E, F, and G input type conversion as well 
as similar types for other languages. 

OTS$CVT_T_G and OTS$CVT_T_H provide run-time support for BASIC and 
FORTRAN input statements. 


Condition Values Returned 


SS$_NORMAL 

OTS$_INPCONERR 


Normal successful completion. 

Input conversion error; an invalid character in 
the input string, or the value is outside the range 
that can be represented. Floating-point-value 
is set to +0.0 (not reserved operand -0.0). 
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OTS$CVT TZ L Convert Hexadecimal Text to Unsigned Integer 

The Convert Hexadecimal Text to Unsigned Integer routine converts an ASCII 
text string representation of an unsigned hexadecimal value to an unsigned 
integer of an arbitrary length. The result is a longword by default, but the calling 
program can specify a byte, word, or longword value. 

Format 

OTS$CVT_TZ_L fixed-or-dynamic-input-string ,varying-output-value 
[.output-value-size] [,flags-value] 

Returns 


Open VMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 

fixed-or-dynamic-input-string 

Open VMS usage char_string 
type character string 

access read only 

mechanism by descriptor, fixed-length or dynamic string 

Input string containing an ASCII text string representation of an unsigned 
hexadecimal value that OTS$CVT_TZ_L converts to an unsigned integer. The 
fixed-or-dynamic-input-string argument is the address of a descriptor pointing 
to the input string. Valid input characters are the space, the digits 0 through 9, 
and the letters A through F (lowercase letters a through f are acceptable). No 
sign is permitted. 

varying-output-value 

OpenVMS usage varying_arg 
type unspecified 

access write only 

mechanism by reference 


Unsigned byte, word, or longword that OTS$CVT_TZ_L creates when it converts 
the ASCII text string. (The value of the output-value-size argument determines 
whether varying-output-value is a byte, word, or longword.) The varying- 
output-value argument is the address of the unsigned integer. 


output-value-size 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 

Number of bytes occupied by the integer value. The output-value-size argument 
contains the number of bytes. If the value size is zero or a negative number, 
OTS$CVT_TZ_L returns an input conversion error. If the number of bytes is 
omitted, the default is 4 (longword). 
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flags-value 

OpenVMS usage 

type 

access 

mechanism 


mask_longword 
longword (unsigned) 
read only 
by value 


User-supplied flags that OTS$CVT_TZ_L uses to determine how blanks are 
interpreted. The flags-value argument is an unsigned longword containing these 
user-supplied flags. 


Bit 0 If set, OTS$CVT_TZ_L ignores blanks. If clear, OTS$CVT_TZ_L 
interprets blanks as zeros. 

jf flags-value is omitted, the default is that all bits are clear. 


Condition Values Returned 

SS$_NORMAL Normal successful completion. 

OTS$_INPCONERR Input conversion error. An invalid character, 

overflow, or invalid output-value-size occurred. 

Examples 

This BASIC program converts a character string representing 
a hexadecimal value to a longword. 


Illustrate (and test) OTS convert hex-string to longword 

EXTERNAL LONG FUNCTION OTS$CVT_TZ_L 
EXTERNAL LONG CONSTANT OTS$_INPCONERR 
INPUT "Enter hex numeric”;HEXVAL$ 

RET_STAT% = OTS$CVT_TZ_L(HEXVAL$, HEX% ) 

PRINT "Conversion error 11 IF RET_STAT% = OTS$_INPCONERR 
PRINT "Decimal value of ";HEXVAL$;" is";HEX% & 

IF RET_STAT% <> OTS$_INPCONERR 

This BASIC example accepts a hexadecimal numeric string, converts it to a 
decimal integer, and prints the result. One sample of the output generated by 
this program is as follows: 


1 . 10 


100 


2 . 


$ RUN HEX 

Enter hex numeric? A 
Decimal value of A is 10 


3EX_CONV: PROCEDURE OPTIONS (MAIN) 

IINCLUDE $STSDEF; /* Include 

DECLARE OTS$CVT_TZ_L ENTRY 

(CHARACTER (*), /* 

FIXED BINARY (31), /* 

FIXED BINARY VALUE, /* 
FIXED BINARY VALUE) /* 
RETURNS (FIXED BINARY (31) 
OPTIONS (VARIABLE); /* 


RETURNS (FIXED BINARY (31)); 
definition of return status values 

Input string passed by descriptor 
Returned value passed by reference 
Size for returned value passed by value 
Flags passed by value 
) /* Return status 

Arguments may be omitted 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


DECLARE INPUT CHARACTER (10); 

DECLARE VALUE FIXED BINARY (31); 

DECLARE FLAGS FIXED BINARY(31) INITIAL(1) READONLY STATIC; /* Ignore blanks */ 
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ON ENDFILE (SYSIN) STOP; 


DO WHILE ('1'B); /* Loop continuously, until end of file 

PUT SKIP (2); 

GET LIST (INPUT) OPTIONS (PROMPT ('Hex value: ')); 

STS$VALUE = OTS$CVT_TZ_L (INPUT, VALUE, , FLAGS); 

IF A STS$SUCCESS THEN RETURN (STS$VALUE); 

PUT SKIP EDIT (INPUT, 'Hex equals', VALUE, 'Decimal') 
(A,X,A,X,F(10),X,A); 


END; 


END HEX_CONV; 


This PL/I example translates a hexadecimal value in ASCII into a fixed 
binary value. This program continues to prompt for input values until the 
user types Ctrl/Z. 

One sample of the output generated by this program is as follows: 


$ RUN HEX 

Hex value: 1A 

1A Hex equals 

26 

Decimal 

Hex value: C 

C Hex equals 

12 

Decimal 

Hex value: Ctrl/Z 




*/ 
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OTS$DIVCx—Complex Division 


The Complex Division routines return a complex result of a division on complex 
numbers. 


Format 

OTS$DIVC complex-dividend ,complex-divisor 
OTS$DIVCD_R3 complex-dividend .complex-divisor 
OTS$DIVCG_R3 complex-dividend .complex-divisor 

Each of these three formats corresponds to one of the three floating-point complex 
types. 

Returns 

OpenVMS usage complex_number 

type F_floating complex, D_floating complex, G_floating complex 

access write only 

mechanism by value 

Complex result of complex division. OTS$DIVC returns an F-floating complex 
number. OTS$DIVCD_R3 returns a D-floating complex number. OTS$DIVCG_R3 
returns a G-floating complex number. 


Arguments 

complex-dividend 

OpenVMS usage complex_number 

type F_floating complex, D_floating complex, G_floating complex 

access read only 

mechanism by value 

Complex dividend. The complex-dividend argument contains a floating-point 
complex value. For OTS$DIVC, complex-dividend is an F-floating complex 
number. For OTS$DIVCD_R3, complex-dividend is a D-floating complex 
number. For OTS$DIVCG_R3, complex-dividend is a G-floating complex 
number. 


complex-divisor 

OpenVMS usage 

type 

access 

mechanism 


complex_number 

F.floating complex, D.floating complex, G.floating complex 
read only 
by value 


Complex divisor. The complex-divisor argument contains the value of the 
divisor. For OTS$DIVC, complex-divisor is an F-floating complex number. 
For OTS$DIVCD_R3, complex-divisor is a D-floating complex number. For 
OTS$DIVCG_R3, complex-divisor is a G-floating complex number. 
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Description 

These routines return a complex result of a division on complex numbers. 
The complex result is computed as follows: 

1. Let (a,b) represent the complex dividend. 

2. Let (c,d) represent the complex divisor. 

3. Let (r,i) represent the complex quotient. 

The results of this computation are as follows: 

r = (ac + bd)/(c 2 + d 2 ) 


i = (be - ad)/(c 2 + d 2 ) 


Condition Values Signaled 

SS$_FLTDIV_F Arithmetic fault. Floating-point division by zero. 

SS$_FLTOVF_F Arithmetic fault. Floating-point overflow. 

Examples 

1. c+ 

C This FORTRAN example forms the complex 
C quotient of two complex numbers using 
C 0TS$DIVC and the FORTRAN random number 
C generator RAN. 

C 

C Declare Zl # Z2, Z_Q, and OTS$DIVC as complex values. 

C 0TS$DIVC will return the complex quotient of Z1 divided 
C by Z2: Z_Q = OTS$DIVC( %VAL(REAL(Zl)), %VAL(AIMAG(Zl), 

C %VAL(REAL(Z2)), %VAL(AIMAG(Z2)) 

C- 

COMPLEX Z1,Z2 / Z_Q / 0TS$DIVC 
C+ 

C Generate a complex number. 

C- 

Z1 = (8.0,4.0) 

C+ 

C Generate another complex number. 

C- 

Z2 = (1.0,1.0) 

c+ 

C Compute the complex quotient of Z1/Z2. 

C- 

Z_Q = OTS$DIVC( %VAL(REAL(Zl)), %VAL(AIMAG(Zl)), %VAL(REAL(Z2)), 

+ %VAL(AIMAG(Z2))) 

TYPE *, ' The complex quotient of',Zl,' divided by ',Z2,' is' 

TYPE *, ' ',Z_Q 

END 

This FORTRAN program demonstrates how to call OTS$DIVC. The output 
generated by this program is as follows: 

The complex quotient of (8.000000,4.000000) divided by (1.000000,1.000000) 
is (6.000000,-2.000000) 
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2. C+ 

C This FORTRAN example forms the complex 

C quotient of two complex numbers by using 
C 0TS$DIVCG_R3 and the FORTRAN random number 
C generator RAN. 

C 

C Declare Zl, Z2, and Z_Q as complex values. 0TS$DIVCG_R3 

C will return the complex quotient of Zl divided by Z2: 

C Z_Q = Z1/Z2 
C- 

C0MPLEX*16 Zl,Z2,Z_Q 
C+ 

C Generate a complex number. 

C- 

Z1 = (8.0,4.0) 

C+ 

C Generate another complex number. 

C- 

Z2 = (1.0,1.0) 

c+ 

C Compute the complex quotient of Z1/Z2. 

C- 

Z_Q = Z1/Z2 

TYPE *, 'The complex quotient of',Zl,' divided by ',Z2,' is' 

TYPE *, ' ', Z_Q 

END 

This FORTRAN example uses the OTS$DIVCG_R3 entry point instead. 
Notice the difference in the precision of the output generated: 

The complex quotient of (8.000000000000000,4.000000000000000) divided by 

( 1 . 000000000000000 , 1 . 000000000000000 ) is 

( 6 . 000000000000000 ,- 2 . 000000000000000 ) 
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OTS$DIV PK LONG—Packed Decimal Division with Long Divisor 

The Packed Decimal Division with Long Divisor routine divides fixed-point 
decimal data, which is stored in packed decimal form, when precision and scale 
requirements for the quotient call for multiple precision division. The divisor 
must have a precision of thirty or thirty-one digits. 

Format 

OTS$DIV_PK_LONG packed-decimal-dividend .packed-decimal-divisor 

.divisor-precision .packed-decimal-quotient .quotient-precision 
.precision-data .scale-data 

Returns 

Open VMS usage 
type 
access 
mechanism 

Arguments 

packed-decimal-dividend 

Open VMS usage varying_arg 
type packed decimal string 

access read only 

mechanism by reference 

Dividend. The packed-decimal-dividend argument is the address of a packed 
decimal string that contains the shifted dividend. 

Before being passed as input, the packed-decimal-dividend argument is always 
multiplied by 10 c where c is defined as follows: 

c = 31 - prec (packed-decimal-dividend) 

Mutiplying packed-decimal-dividend by 10 c makes packed-decimal- 
dividend a 31-digit number. 

packed-decimal-divisor 

Open VMS usage varyingarg 
type packed decimal string 

access read only 

mechanism by reference 

Divisor. The packed-decimal-divisor argument is the address of a packed 
decimal string that contains the divisor. 

divisor-precision 

OpenVMS usage word_signed 
type word (signed) 

access read only 

mechanism by value 

Precision of the divisor. The divisor-precision argument is a signed word that 
contains the precision of the divisor. The high-order bits are filled with zeros. 


cond_value 
longword (unsigned) 
write only 
by value 
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packed-decimal-quotient 

Open VMS usage varying_arg 
type packed decimal string 

access write only 

mechanism by reference 

Quotient. The packed-decimal-quotient argument is the address of the packed 
decimal string into which OTS$DIV_PK_LONG writes the quotient. 

quotient-precision 

OpenVMS usage word_signed 
type word (signed) 

access read only 

mechanism by value 

Precision of the quotient. The quotient-precision argument is a signed word 
that contains the precision of the quotient. The high-order bits are filled with 
zeros. 

precision-data 

OpenVMS usage word_signed 
type word (signed) 

access read only 

mechanism by value 

Additional digits of precision required. The precision-data argument is a signed 
word that contains the value of the additional digits of precision required. 

OTS$DIV_PK_LONG computes the precision-data argument as follows: 

precision-data = scale (packed-decimal-quotient) 

+ scale (packed-decimal-divisor) 

- scale (packed-decimal-dividend) 

- 31 + prec (packed-decimal-dividend) 

scale-data 

OpenVMS usage word_signed 
type word (signed) 

access read only 

mechanism by value 

Scale factor of the decimal point. The scale-data argument is a signed word that 
contains the scale data. 

OTS$DIV_PK_LONG defines the scale-data argument as follows: 
scale-data = 31 - prec (packed-decimal-divisor) 
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Description 



Before using this routine on an OpenVMS for VAX system, you should determine 
whether it is best to use OTS$DIV_PK_LONG, OTS$DIV_PK_SHORT, or the 
VAX instruction DIVP. To determine this, you must first calculate b, where b is 
defined as follows: 

b = scale (packed-decimal-quotient) 

+ scale (packed-decimal-divisor) 

- scale (packed-decimal-dividend) 

+ prec (packed-decimal-dividend) 

If b is greater than 31, then OTS$DIV_PK_LONG can be used to perform the 
division. If b is less than 31, you could use the instruction DIVP instead. ♦ 

When using this routine on an OpenVMS AXP system, or on an OpenVMS 
VAX system and you have determined that you cannot use DIVP, you need 
to determine whether you should use OTS$DIV_PK_LONG or OTS$DIV_PK_ 
SHORT. To determine this, you must examine the value of scale-data. If scale- 
data is less than or equal to 1, then you should use OTS$DIV_PK_LONG. If 
scale-data is greater than 1, you should use OTS$DIV_PK_SHORT instead. 


Condition Value Signaled 

SS$_FLTDIV 

Example 


i 

OPTION 

TYPE = EXPLICIT 


Fatal error. Division by zero. 


& 




+ 

This program uses OTS$DIV_PK_LONG to perform packed decimal 
division. 

+ 

DECLARATIONS 


DECLARE DECIMAL (31, 2) NATIONAL_DEBT 

DECLARE DECIMAL (30, 3) POPULATION 

DECLARE DECIMAL (10, 5) PER_CAPITA_DEBT 

EXTERNAL SUB OTS$DIV_PK_LONG (DECIMAL(31,2), DECIMAL (30, 3), & 
WORD BY VALUE, DECIMAL(10, 5), WORD BY VALUE, WORD BY VALUE, & 
WORD BY VALUE) 


! + 

! Prompt the user for the required input. 

INPUT "Enter national debt: ”;NATIONAL_DEBT 
INPUT "Enter current population: ";POPULATION 
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+ 

Perform the division and print the result. 


scale(divd) = 2 
scale(divr) = 3 
scale(quot) = 5 

prec(divd) = 31 
prec(divr) =30 
prec(quot) =10 


prec-data = scale(quot) + scale(divr) - scale(divd) - 31 + 
prec(divd) 

prec-data =5 +3 - 2 -31+31 

prec-data = 6 

b = scale(quot) + scale(divr) - scale(divd) + prec(divd) 
b = 5 + 3 - 2 + 31 

b = 37 

c = 31 - prec(divd) 
c = 31 - 31 

c = 0 

scale-data = 31 - prec(divr) 
scale-data = 31 - 30 

scale-data = 1 

b is greater than 31, so either OTS$DIV_PK_LONG or 

OTS$DIV_PK_SHORT may be used to perform the division. 

If b is less than or equal to 31, then the DIVP 
instruction may be used. 

scale-data is less than or equal to 1, so OTS$DIV_PK_LONG 
should be used instead of OTS$DIV_PK_SHORT. 


CALL OTS$DIV_PK_LONG( NATIONAL_DEBT, POPULATION, '30'W, PER_CAPITA_DEBT, & 
'10'W, '6'W, 'l'W) 

PRINT "The per capita debt is ";PER_CAPITA_DEBT 
END 

This BASIC example program uses OTS$DIV_PK_LONG to perform packed 
decimal division. One example of the output generated by this program is as 
follows: 

$ RUN DEBT 

Enter national debt: ? 12345678 

Enter current population: ? 1212 

The per capita debt is 10186.20297 
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OTS$DIV_PK_SHORT—Packed Decimal Division with Short Divisor 

The Packed Decimal Division with Short Divisor routine divides fixed-point 
decimal data when precision and scale requirements for the quotient call for 
multiple-precision division. 

Format 

OTS$DIV_PK_SHORT packed-decimal-dividend ,packed-decimal-divisor 

,divisor-precision ,packed-decimal-quotient 
,quotient-precision ,precision-data 

Returns 

Open VMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Arguments 

packed-decimal-dividend 

OpenVMS usage varying_arg 
type packed decimal string 

access read only 

mechanism by reference 

Dividend. The packed-decimal-dividend argument is the address of a packed 
decimal string that contains the shifted dividend. 

Before being passed as input, the packed-decimal-dividend argument is always 
multiplied by 10 c where c is defined as follows: 

c = 31 - prec(packed-decimal-dividend) 

Multiplying packed-decimal-dividend by 10 c makes packed-decimal- 
dividend a 31-digit number. 

packed-decimal-divisor 

OpenVMS usage varying_arg 
type packed decimal string 

access read only 

mechanism by reference 

Divisor. The packed-decimal-divisor argument is the address of a packed 
decimal string that contains the divisor. 

divisor-precision 

OpenVMS usage word_signed 
type word (signed) 

access read only 

mechanism by value 

Precision of the divisor. The divisor-precision argument is a signed word 
integer that contains the precision of the divisor. The high-order bits are filled 
with zeros. 
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packed-decimal-quotient 

OpenVMS usage varying_arg 
type packed decimal string 

access write only 

mechanism by reference 

Quotient. The packed-decimal-quotient argument is the address of a packed 
decimal string into which OTS$DIV_PK_SHORT writes the quotient. 

quotient-precision 

OpenVMS usage word_signed 
type word (signed) 

access read only 

mechanism by value 

Precision of the quotient. The quotient-precision argument is a signed word 
that contains the precision of the quotient. The high-order bits are filled with 
zeros. 

precision-data 

OpenVMS usage word_signed 
type word (signed) 

access read only 

mechanism by value 

Additional digits of precision required. The precision-data argument is a signed 
word that contains the value of the additional digits of precision required. 

OTS$DIV_PK_SHORT computes the precision-data argument as follows: 

precision-data = scale (packed-decimal-quotient) 

+ scale (packed-decimal-divisor) 

- scale (packed-decimal-dividend) 

- 31 + prec (packed-decimal-dividend) 


Description 



Before using this routine on an OpenVMS for VAX system, you should determine 
whether it is best to use OTS$DIV_PK_LONG, OTS$DIV_PK_SHORT, or the 
VAX instruction DIVP. To determine this, you must first calculate b, where b is 
defined as follows: 

b = scale (packed-decimal-quotient) + scale (packed-decimal-divisor) - 
scale (packed-decimal-dividend) + prec (packed-decimal-dividend) 

If b is greater than 31, then OTS$DIV_PK_SHORT can be used to perform the 
division. If 6 is less than 31, you could use the VAX instruction DIVP instead. ♦ 


When using this routine on an OpenVMS AXP system, or on an OpenVMS 
for VAX system and you have determined that you cannot use DIVP, you need 
to determine whether you should use OTS$DIV_PK_LONG or OTS$DIV_PK_ 
SHORT. To determine this, you must examine the value of scale-data. If scale- 
data is less than or equal to 1, then you should use OTS$DIV_PK_LONG. If 
scale-data is greater than 1, you should use OTS$DIV_PK_SHORT instead. 
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Condition Value Signaled 

SS$_FLTDIV 


Fatal error. Division by zero. 
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0TS$M0VE3—Move Data Without Fill 

The Move Data Without Fill routine moves up to 2 31 -1 bytes (2,147,483,647 
bytes) from a specified source address to a specified destination address. 


Format 

OTS$MOVE3 length-value ,source-array .destination-array 

corresponding jsb entry point 

OTS$MOVE3_R5 

Returns 

None. 

Arguments 

length-value 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 

Number of bytes of data to move. The length-value argument is a signed 
longword that contains the number of bytes to move. The value of length-value 
may range from 0 to 2,147,483,647 bytes. 

source-array 

OpenVMS usage vector_byte_unsigned 
type byte (unsigned) 

access read only 

mechanism by reference, array reference 

Data to be moved by OTS$MOVE3. The source-array argument contains the 
address of an unsigned byte array that contains this data. 

destination-array 

OpenVMS usage vector_byte_unsigned 
type byte (unsigned) 

access write only 

mechanism by reference, array reference 

Address into which source-array will be moved. The destination-array 
argument is the address of an unsigned byte array into which OTS$MOVE3 
writes the source data. 
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Description 

OTS$MOVE3 performs the same function as the VAX MOVC3 instruction except 
that the length-value is a longword integer rather than a word integer. When 
called from the JSB entry point, the register outputs of OTS$MOVE3_R5 follow 
the same pattern as those of the MOVC3 instruction: 

RO 0 

■^1 Address of one byte beyond the source string 

R2 0 

R3 Address of one byte beyond the destination string 

R4 0 

R5 0 

For more information, see the description of the MOVC3 instruction in the VAX 
Architecture Reference Manual. See also the routine LIB$MOVC3, which is a 
callable version of the MOVC3 instruction. 

Condition Values Returned 

None. 
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0TS$M0VE5—Move Data with Fill 

The Move Data with Fill routine moves up to 2 31 —1 bytes (2,147,483,647 
bytes) from a specified source address to a specified destination address, with 
separate source and destination lengths, and with fill. Overlap of the source and 
destination arrays does not affect the result. 

Format 

OTS$MOVE5 longword-int-source-length .source-array .fill-value 
,longword-int-dest-length .destination-array 

corresponding jsb entry point 

OTS$MOVE5_R5 

Returns 

None. 

Arguments 

longword-int-source-length 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 

Number of bytes of data to move. The longword-int-source-length argument 
is a signed longword that contains this number. The value of longword-int- 
source-length may range from 0 to 2,147,483,647. 

source-array 

OpenVMS usage vector_byte_unsigned 
type byte (unsigned) 

access read only 

mechanism by reference, array reference 

Data to be moved by OTS$MOVE5. The source-array argument contains the 
address of an unsigned byte array that contains this data. 

fill-value 

OpenVMS usage byte_unsigned 
type byte (unsigned) 

access read only 

mechanism by value 

Character used to pad the source data if longword-int-source-length is less 
than longword-int-dest-length. The fill-value argument contains the address 
of an unsigned byte that is this character. 

longword-int-dest-length 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 
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Size of the destination area in bytes. The longword-int-dest-length argument 
is a signed longword containing this size. The value of longword-int-dest- 
length may range from 0 through 2,147,483,647. 

destination-array 

Open VMS usage vector_byte_unsigned 
type byte (unsigned) 

access write only 

mechanism by reference, array reference 

Address into which source-array is moved. The destination-array argument is 
the address of an unsigned byte array into which OTS$MOVE5 writes the source 
data. 


Description 

OTS$MOVE5 performs the same function as the VAX MOVC5 instruction 
except that the longword-int-source-length and longword-int-dest-length 
arguments are longword integers rather than word integers. When called from 
the JSB entry point, the register outputs of OTS$MOVE5_R5 follow the same 
pattern as those of the MOVC5 instruction: 

RO Number of unmoved bytes remaining in source string 

R1 Address of one byte beyond the source string 

R2 0 

R3 Address of one byte beyond the destination string 

R4 0 

R5 0 

For more information, see the description of the MOVC5 instruction in the VAX 
Architecture Reference Manual. See also the routine LIB$MOVC5, which is a 
callable version of the MOVC5 instruction. 

Condition Values Returned 

None. 
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OTS$MULCx—Complex Multiplication 

The Complex Multiplication routines calculate the complex product of two 
complex values. 

Format 

OTS$MULCD_R3 complex-multiplier .complex-multiplicand 
OTS$MULCG_R3 complex-multiplier .complex-multiplicand 
These formats correspond to the D-floating and G-floating complex types. 

Returns 

OpenVMS usage complex_number 

type D_floating complex, G_floating complex 

access write only 

mechanism by value 

Complex result of multiplying two complex numbers. OTS$MULCD_R3 returns 
a D-floating complex number. OTS$MULCG_R3 returns a G-floating complex 
number. 


Arguments 

complex-multiplier 

OpenVMS usage complex_number 

type D_floating complex, G_floating complex 

access read only 

mechanism by value 

Complex multiplier. The complex-multiplier argument contains the complex 
multiplier. For OTS$MULCD_R3, complex-multiplier is a D-floating complex 
number. For OTS$MULCG_R3, complex-multiplier is a G-floating complex 
number. 

complex-multiplicand 

OpenVMS usage complex_number 

type D.floating complex, G.floating complex 

access read only 

mechanism by value 

Complex multiplicand. The complex-multiplicand argument contains the 
complex multiplicand. For OTS$MULCD_R3, complex-multiplicand is a D- 
floating complex number. For OTS$MULCG_R3, complex-multiplicand is an 
F-floating complex number. 


Description 

OTS$MULCD_R3 and OTS$MULCG_R3 calculate the complex product of two 
complex values. 

The complex product is computed as follows: 

1. Let (a,b) represent the complex multiplier. 

2. Let (c,d) represent the complex multiplicand. 
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3. Let (r,i) represent the complex product. 
The results of this computation are as follows: 


(a, * (c, d) — (ac — bd ) \/— 1 (ad -+■ be) 

Therefore : r = ac — bd 
Therefore : i = ad + be 


Condition Values Signaled 

SS$_FLTOVF_F Floating value overflow can occur. 

SS$_ROPRAND Reserved operand. OTS$MULCx encountered 

a floating-point reserved operand because of 
incorrect user input. A floating-point reserved 
operand is a floating-point datum with a sign bit 
of 1 and a biased exponent of zero. Floating-point 
reserved operands are reserved for future use by 
Digital. 

Example 

c+ 

C This FORTRAN example forms the product of 
C two complex numbers using 0TS$MULCD_R3 
C and the FORTRAN random number generator RAN. 

C 

C Declare Zl, Z2, and Z_Q as complex values. 0TS$MULCD_R3 
C returns the complex product of Zl times Z2: 

C Z_Q = Zl * Z2 
C- 

C0MPLEX*16 Zl,Z2,Z_Q 
C+ 

C Generate a complex number. 

C- 

Z1 = (8.0,4.0) 

C+ 

C Generate another complex number. 

C- 

Z2 = (2.0,3.01 
C+ 

C Compute the complex product of Z1*Z2. 

C- 

Z_Q = Zl * Z2 

TYPE *, ' The complex product of',Zl,' times ',Z2,' is' 

TYPE ' ',Z_Q 

END 

This FORTRAN example uses OTS$MULCD_R3 to multiply two complex 
numbers. The output generated by this program is as follows: 

The complex product of (8.000000000000000,4.000000000000000) times 
(2.000000000000000,3.000000000000000) is 
(4.000000000000000,32.00000000000000) 
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OTS$POWCxCx—Raise a Complex Base to a Complex Floating-Point 

Exponent 

The Raise a Complex Base to a Complex Floating-Point Exponent routines raise a 
complex base to a complex exponent. 

Format 

OTS$POWCC complex-base ,complex-exponent-value 

OTS$POWCDCD_R3 complex-base ,complex-exponent-value 

OTS$POWCGCG_R3 complex-base .complex-exponent-value 

Each of these three formats corresponds to one of the three floating-point complex 
types. 

Returns 

OpenVMS usage complex_number 

type F_floating complex, D_floating complex, G_floating complex 

access write only 

mechanism by value 

Result of raising a complex base to a complex exponent. OTS$POWCC returns 
an F-floating complex number. OTS$POWCDCD_R3 returns a D-floating complex 
number. OTS$POWCGCG_R3 returns a G-floating complex number. 

Arguments 

complex-base 

OpenVMS usage complex_number 

type F_floating complex, D_floating complex, G_floating complex 

access read only 

mechanism by value 

Complex base. The complex-base argument contains the value of the base. 

For OTS$POWCC, complex-base is an F-floating complex number. For 
OTS$POWCDCD_R3, complex-base is a D-floating complex number. For 
OTS$POWCGCG_R3, complex-base is a G-floating complex number. 

complex-exponent-value 

OpenVMS usage complex_number 

type F_floating complex, D_floating complex, G_floating complex 

access read only 

mechanism by value 

Complex exponent. The complex-exponent-value argument contains the value 
of the exponent. For OTS$POWCC, complex-exponent-value is an F-floating 
complex number. For OTS$POWCDCD_R3, complex-exponent-value is a 
D-floating complex number. For OTS$POWCGCG_R3, complex-exponent-value 
is a G-floating complex number. 
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Description 

OTS$POWCC, OTS$POWCDCD_R3 and 0TS$P0WCGCG_R3 raise a complex 
base to a complex exponent. The American National Standard FORTRAN-77 
(ANSI X3.9-1978) defines complex exponentiation as follows: 

x v = exp(y * log(x)) 


In this example, x and y are type COMPLEX. 

Condition Values Signaled 

MTH$_INVARGMAT Invalid argument in math library. Base is (0.,0.). 

MTH$_FLOOVEMAT Floating-point overflow in math library. 

SS$_ROPRAND Reserved operand. 

Examples 

i. c+ 

C This FORTRAN example raises a complex base to a complex 
C power using OTS$POWCC. 

C 

C Declare Zl, Z2, Z3, and OTS$POWCC as complex values. Then OTS$POWCC 

C returns the complex result of Z1**Z2: Z3 = 0TS$P0WCC(Z1,Z2), 

C where Zl and Z2 are passed by value. 

C- 

COMPLEX Zl,Z2,Z3,OTS$POWCC 

c+ 

C Generate a complex base. 

C- 

Z1 = (2.0,3.01 
C+ 

C Generate a complex power. 

C- 

Z2 = (1.0,2.01 
C+ 

C Compute the complex value of Z1**Z2. 

C- 

Z3 = OTS$POWCC( %VAL(REAL(Z1)), %VAL(AIMAG(Zl)), 

+ %VAL(REAL(Z2)), %VAL(AIMAG(Z2))) 

TYPE *, ' The value of',Zl,'** # ,Z2,' is',Z3 
END 

This FORTRAN example uses OTS$POWCC to raise an F-floating complex 
base to an F-floating complex exponent. 

The output generated by this program is as follows: 

The value of (2.000000,3.000000)** (1.000000,2.000000) is 
(-0.4639565,-0.1995301) 
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C This FORTRAN example raises a complex base to a complex 
C power using 0TS$P0WCGCG_R3. 

C 

C Declare Zl, Z2, and Z3 as complex values. 0TS$P0WCGCG_R3 
C returns the complex result of Zl**Z2: Z3 = Zl**Z2. 

C- 

C0MPLEX*16 Zl,Z2,Z3 
C+ 

C Generate a complex base. 

C- 

Z1 = (2.0,3.01 
C+ 

C Generate a complex power. 

C- 

Z2 = (1.0,2.0) 

C+ 

C Compute the complex value of Z1**Z2. 

C- 

Z3 = Zl**Z2 
TYPE 1,Z1,Z2,Z3 

1 FORMAT(' The value of (',Fll.8,,F11.8,')**(',F11.8, 

+ ',',Fll.8,') is (',Fll.8,',',F11.8,')•') 

END 

This FORTRAN example program shows how to use OTS$POWCGCG_R3. 
Notice the high precision in the output generated by this program: 

The value of ( 2.00000000, 3.00000000)**( 1.00000000, 2.00000000) is 
(-0.46395650,-0.46395650). 
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OTS$POWCxJ—Raise a Complex Base to a Signed Longword Integer 

Exponent 

The Raise a Complex Base to a Signed Longword Integer Exponent routines 
return the complex result of raising a complex base to an integer exponent. 


Format 

OTS$POWCJ complex-base Jongword-integer-exponent 

OTS$POWCDJ_R3 complex-base Jongword-integer-exponent 

OTS$POWCGJ_R3 complex-base Jongword-integer-exponent 

Each of these three formats corresponds to one of the three floating-point complex 
types. 

Returns 

OpenVMS usage complex_number 

type F_floating complex, D_floating complex, G_floating complex 

access write only 

mechanism by value 

Complex result of raising a complex base to an integer exponent. OTS$POWCJ 
returns an F-floating complex number. OTS$POWCDJ_R3 returns a D-floating 
complex number. OTS$POWCGJ_R3 returns a G-floating complex number. In 
each format, the result and base are of the same data type. 

Arguments 

complex-base 

OpenVMS usage complex_number 

type F_floating complex, D_floating complex, G_floating complex 

access read only 

mechanism by value 

Complex base. The complex-base argument contains the complex base. 

For OTS$POWCJ, complex-base is an F-floating complex number. For 
OTS$POWCDJ_R3, complex-base is a D-floating complex number. For 
OTS$POWCGJ_R3, complex-base is a G-floating complex number. 

longword-integer-exponent 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 

Exponent. The longword-integer-exponent argument is a signed longword 
containing the exponent. 
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Description 


OTS$POWCJ, OTS$POWCDJ_R3, and 0TS$P0WCGJ_R3 return the complex 
result of raising a complex base to an integer exponent. The complex result is as 
follows: 


Base 

Exponent 

Result 

Any 

> 0 

The product of (base**2 1 ), where i is each nonzero 

bit in longword-integer-exponent 

(0.,0.) 

< o 

Undefined exponentiation 

Not (0.,0.) 

<0 

The product of (base**2 i ), where i is each nonzero 

bit in longword-integer-exponent 

Not (0.,0.) 

0 

(1.0,0.0) 


Condition Values Signaled 

SS$_FLTDIV 

SS$_FLTOVF 

MTH$_UNDEXP 


Floating-point division by zero. 
Floating-point overflow. 
Undefined exponentiation. 


Example 

c+ 

C This FORTRAN example raises a complex base to 
C a NONNEGATIVE integer power using 0TS$P0WCJ. 

C 

C Declare Zl, Z2, Z3, and 0TS$P0WCJ as complex values. 

C Then 0TS$P0WCJ returns the complex result of 
C Zl**Z2: Z3 = 0TS$P0WCJ(Zl,Z2), 

C where Zl and Z2 are passed by value. 

C- 

COMPLEX Zl ; Z3,0TS$P0WCJ 
INTEGER Z2 
C+ 

C Generate a complex base. 

C- 

Z1 = (2.0,3.0) 

C+ 

C Generate an integer power. 

C- 

Z2 = 2 
C+ 

C Compute the complex value of Z1**Z2. 

C- 

Z3 = OTS$POWCJ( %VAL(REAL(Zl)), %VAL(AIMAG(Zl)), %VAL(Z2)) 
TYPE 1,Zl,Z2,Z3 

1 FORMAT (' The value of (', F10.8, ', ', FU. 8, ') ** Ml, ' is 
+ (',Fll. 8, ', ',F12. 8, ') •') 

END 

The output generated by this FORTRAN program is as follows: 

The value of (2.00000000, 3.00000000)**2 is 
(-5.00000000, 12.00000000). 
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OTS$POWDD—Raise a D-Floating Base to a D-Floating Exponent 

The Raise a D-Floating Base to a D-Floating Exponent routine raises a D-floating 
base to a D-floating exponent. 

Format 

OTS$POWDD D-floating-point-base ,D-floating-point-exponent 

Returns 

Open VMS usage floating_point 
type D_floating 

access write only 

mechanism by value 

Arguments 

D-floating-point-base 

OpenVMS usage floating_point 
type D_floating 

access read only 

mechanism by value 

Base. The D-floating-point-base argument is a D-floating number containing 
the base. 

D-floating-point-exponent 

OpenVMS usage floating_point 
type D_floating 

access read only 

mechanism by value 

Exponent. The D-floating-point-exponent argument is a D-floating number 
that contains the exponent. 


Description 

OTS$POWDD raises a D-floating base to a D-floating exponent. 

The internal calculations and the floating-point result have the same precision as 
the base value. 

The D-floating result for OTS$POWDD is given by the following: 


Base 

Exponent 

Result 

= 0 

> 0 

0.0 

= 0 

= 0 

Undefined exponentiation 

= 0 

< 0 

Undefined exponentiation 

< 0 

Any 

Undefined exponentiation 

> 0 

> 0 

2 [exponent *\og2{base)\ 

> 0 

= 0 

1.0 
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Base 

Exponent 

Result 

> 0 

< 0 

2 [exponent*\og 2 (base)\ 


Floating-point overflow can occur. 

Undefined exponentiation occurs if the base is zero and the exponent is zero or 
negative, or if the base is negative. 


Condition Values Signaled 

MTH$_FLOOVEMAT 

MTH$_FLOUNDMAT 

MTH$_UNDEXP 


Floating-point overflow in math library. 
Floating-point underflow in math library. 

Undefined exponentiation. This error is signaled 

if D-floating-point-base is zero and D-floating- 
point-exponent is zero or negative, or if the 
D-floating-point-base is negative. 
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OTS$POWDR—Raise a D-Floating Base to an F-Floating Exponent 

The Raise a D-Floating Base to an F-Floating Exponent routine raises a D- 
floating base to an F-floating exponent. 


Format 


Returns 


OTS$POWDR D-floating-point-base , F-floating-point-exponent 


Open VMS usage 

type 

access 

mechanism 


floating_point 
D_floating 
write only 
by value 


Arguments 

D-floating-point-base 

Open VMS usage floating_point 
type D_floating 

access read only 

mechanism by value 


Base. The D-floating-point-base argument is a D-floating number containing 
the base. 


F-floating-point-exponent 

Open VMS usage floating_point 
type F_floating 

access read only 

mechanism by value 


Exponent. The F-floating-point-exponent argument is an F-floating number 
that contains the exponent. 


Description 

OTS$POWDR raises a D-floating base to an F-floating exponent. 

The internal calculations and the floating-point result have the same precision as 
the base value. 

OTS$POWDR converts the F-floating exponent to a D-floating number. The 
D-floating result for OTS$POWDR is given by the following: 


Base 

Exponent 

Result 

= 0 

> 0 

0.0 

= 0 

= 0 

Undefined exponentiation 

= 0 

< 0 

Undefined exponentiation 

< 0 

Any 

Undefined exponentiation 

> 0 

> 0 

2 [exponent*\og2.(base)] 

> 0 

= 0 

1.0 
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Base 

Exponent 

Result 

> 0 

< 0 

2 [exponent *log2(base)] 


Floating-point overflow can occur. 

Undefined exponentiation occurs if the base is zero and the exponent is zero or 
negative, or if the base is negative. 


Condition Values Signaled 

SS$_FLTOVF 

MTH$_FLOOVEMAT 

MTH$_FLOUNDMAT 

MTH$_UNDEXP 


Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 

Floating-point overflow in math library. 
Floating-point underflow in math library. 
Undefined exponentiation. This error is signaled 

if D-floating-point-base is zero and F-floating- 
point-exponent is zero or negative, or if the 
D-floating-point-base is negative. 
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OTS$POWDJ—Raise a D-Floating Base to a Longword Exponent 

The Raise a D-Floating Base to a Longword Exponent routine raises a D-floating 
base to a longword exponent. 


Format 

OTS$POWDJ D-floating-point-base Jongword-integer-exponent 

Returns 


Open VMS usage 

type 

access 

mechanism 


floating_point 
D_floating 
write only 
by value 


Arguments 


D-floating-point-base 

Open VMS usage floating_point 
type D_floating 

access read only 

mechanism by value 

Base. The D-floating-point-base argument is a D-floating number containing 
the base. 


longword-integer-exponent 

Open VMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 

Exponent. The longword-integer-exponent argument is a signed longword 
that contains the signed longword integer exponent. 


Description 

OTS$POWDJ raises a D-floating base to a longword exponent. 

The internal calculations and the floating-point result have the same precision as 
the base value. 

The floating-point result is as follows: 


Base Exponent Result 


Any 

> 0 

Product of (base**2 1 ) where i is each nonzero bit 
position in longword-integer-exponent 

> 0 

= 0 

1.0 

= 0 

= 0 

Undefined exponentiation 

< 0 

= 0 

1.0 

> 0 

< 0 

1.0/ (base**2 1 ), where i is each nonzero bit position in 

longword-integer-exponent 
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Base 

Exponent 

Result 

= 0 

< 0 

Undefined exponentiation 

< 0 

< 0 

1.0/ (base**2 i ) where i is each nonzero bit position in 



longword-integer-exponent 


Floating-point overflow can occur. 

Undefined exponentiation occurs if the base is zero and the exponent is zero or 
negative. 


Condition Values Signaled 

SS$_FLTOVF 

MTH$_FLOOVEMAT 

MTH$_FLOUNDMAT 

MTH$_UNDEXP 


Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 
Floating-point overflow in math library. 
Floating-point underflow in math library. 
Undefined exponentiation. This error is signaled 
if D-floating-point-base is zero and longword- 
integer-exponent is zero or negative, or if the 
D-floating-point-base is negative. 
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OTS$POWGG—Raise a G-Floating Base to a G-Floating Exponent 


The Raise a G-Floating Base to a G-Floating Exponent routine raises a G-floating 
base to a G-floating exponent. 


Format 


OTS$POWGG G-floating-point-base ,G-floating-point-exponent 

Returns 


Open VMS usage 

type 

access 

mechanism 


floating_point 
G_floating 
write only 
by value 


Arguments 

G-floating-point-base 

Open VMS usage floating_point 
type G_floating 

access read only 

mechanism by value 


Base that OTS$POWGG raises to a G-floating exponent. The G-floating-point- 
base argument is a G-floating number containing the base. 


G-floating-point-exponent 

OpenVMS usage floating_point 
type G_floating 

access read only 

mechanism by value 

Exponent to which OTS$POWGG raises the base. The G-floating-point- 
exponent argument is a G-floating number containing the exponent. 


Description 

OTS$POWGG raises a G-floating base to a G-floating exponent. 

The internal calculations and the floating-point result have the same precision as 
the base value. 

The G-floating result for OTS$POWGG is as follows: 


Base Exponent Result 


= 0 

> 0 

0.0 

= 0 

= 0 

Undefined exponentiation 

= 0 

< 0 

Undefined exponentiation 

< 0 

Any 

Undefined exponentiation 

> 0 

> 0 

2 [exponent*\og2(base)\ 

> 0 

= 0 

1.0 
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Base 

Exponent 

Result 

> 0 

< 0 

2 [exponent *\og2(base)] 


Floating-point overflow can occur. 


Undefined exponentiation occurs if the base is zero and the exponent is zero or 
negative, or if the base is negative. 


Condition Values Signaled 

SS$_FLTOVF 

MTH$_FLOOVEMAT 

MTH$_FLOUNDMAT 

MTH$_UNDEXP 


Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 
Floating-point overflow in math library. 
Floating-point underflow in math library. 
Undefined exponent. This error is signaled if 
G-floating-point-base is zero and G-floating- 
point-exponent is zero or negative, or if G- 
floating-point-base is negative. 


Example 


C This example demonstrates the use of 0TS$P0WGG, 

C which raises a G-floating point base 

C to a G-floating point power. 

C- • 

REAL*8 X,Y,RESULT,0TS$P0WGG 
C+ 

C The arguments of OTS$POWGG are passed by value. FORTRAN can 
C only pass INTEGER and REAL*4 expressions as VALUE. Since 
C INTEGER and REAL*4 values are one longword long, while REAL*8 
C values are two longwords long, equate the base (and power) to 

C two-dimensional INTEGER vectors. These vectors will be passed 

C by VALUE. 

C- 

INTEGER N{2),M(2) 

EQUIVALENCE (N(1),X), (M(1),Y) 

X = 8.0 

Y = 2.0 

c+ , 

C To pass X by value, pass N(1) and N(2) by value. Similarly for Y. 

C- 

RESULT = OTS$POWGG(%VAL(N(l)),%VAL(N(2)),%VAL(M(1)),%VAL(M(2))) 

TYPE 8.0**2.0 IS ',RESULT 
X = 9.0 

Y = -0.5 

c+ _ , 

C In FORTRAN, OTS$POWWGG is indirectly called by simply using the 
C exponentiation operator. 

C- 

RESULT = X**Y 

TYPE V 9.0**-0.5 IS RESULT 
END 

T his FORTRAN example uses OTS$POWGG to raise a G-floating base to a 
G-floating exponent. 
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The output generated by this example is as follows: 

8.0**2.0 IS 64.0000000000000 
9.0**-0.5 IS 0.333333333333333 
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OTS$POWGJ—Raise a G-Floating Base to a Longword Exponent 

The Raise a G-Floating Base to a Longword Exponent routine raises a G-floating 
base to a longword exponent. 


Format 

OTS$POWGJ G-floating-point-base .longword-integer-exponent 

Returns 

OpenVMS usage floating_point 
type G_floating 

access write only 

mechanism by value 


Arguments 

G-floating-point-base 

OpenVMS usage floating_point 
type G_floating 

access read only 

mechanism by value 

Base that OTS$POWGJ raises to a longword exponent. The G-floating-point- 
base argument is a G-floating number containing the base. 

longword-integer-exponent 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 

Exponent to which OTS$POWGJ raises the base. The longword-integer- 
exponent argument is a signed longword containing the exponent. 

Description 

OTS$POWGJ raises a G-floating base to a longword exponent. 

The internal calculations and the floating-point result have the same precision as 
the base value. 

The floating-point result is as follows: 


Base 

Exponent 

Result 

Any 

> 0 

Product of (base**2 i ) where i is each nonzero bit 

position in longword-integer-exponent 

> 0 

= 0 

1.0 

= 0 

= 0 

Undefined exponentiation 

< 0 

= 0 

1.0 

> 0 

< 0 

1.0/ (base**2 i ), where i is each nonzero bit position in 


longword-integer-exponent 
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Base 

Exponent 

Result 

= 0 

< 0 

Undefined exponentiation 

< 0 

< 0 

1.0/ (base**2 1 ) where i is each nonzero bit position in 

longword-integer-exponent 


Floating-point overflow can occur. 

Undefined exponentiation occurs if the base is zero and the exponent is zero or 
negative. 


Condition Values Signaled 

SS$_FLTOVF 

MTH$_FLOOVEMAT 

MTH$_FLOUNDMAT 

MTH$_UNDEXP 


Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 
Floating-point overflow in math library. 
Floating-point underflow in math library. 

Undefined exponent. This error is signaled if 

G-floating-point-base is zero and longword- 
integer-exponent is zero or negative, or if 
G-floating-point-base is negative. 
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0TS$P0WHH_R3—Raise an H-Floating Base to an H-Floating 

Exponent (VAX VMS Only) 



On an OpenVMS for VAX system, the Raise an H-Floating Base to an H-Floating 
Exponent routine raises an H-floating base to an H-floating exponent. 


Format 


OTS$POWHH_R3 H-floating-point-base ,H-floating-point-exponent 


Returns 


OpenVMS usage 

type 

access 

mechanism 


floating_point 
H_floating 
write only 
by value 


Arguments 

H-floating-point-base 

OpenVMS usage floating_point 
type H_floating 

access read only 

mechanism by value 

Base. The H-floating-point-base argument is an H-floating number containing 
the base. 

H-floating-point-exponent 

OpenVMS usage floating_point 
type H_floating 

access read only 

mechanism by value 

Exponent. The H-floating-point-exponent argument is an H-floating number 
that contains the H-floating exponent. 


Description 

OTS$POWHH_R3 raises an H-floating base to an H-floating exponent. 

The internal calculations and the floating-point result have the same precision as 
the base value. 

The H-floating result for OTS$POWHH_R3 is as follows: 


Base 

Exponent 

Result 

= 0 

> 0 

0.0 

= 0 

= 0 

Undefined exponentiation 

= 0 

< 0 

Undefined exponentiation 

< 0 

Any 

Undefined exponentiation 

> 0 

> 0 

2 [exponent*\og 2 (base)\ 
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Base 

Exponent 

Result 

> 0 

= 0 

1.0 

> 0 

< 0 

2 [exponent*\og2(base)\ 


Floating-point overflow can occur. 


Undefined exponentiation occurs if the base is zero and the exponent is zero or 
negative, or if the base is negative. 

Condition Values Signaled 


SS$_FLTOVF 

MTH$_FLOOVEMAT 

MTH$_FLOUNDMAT 

MTH$_UNDEXP 


Example 


Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 

Floating-point overflow in math library. 
Floating-point underflow in math library. 

Undefined exponentiation. This error is signaled 

if H-floating-point-base is zero and H-floating- 
point-exponent is zero or negative, or if the 
H-floating-point-base is negative. 


C+ 

C Example of 0TS$P0WHH, which raises an H_floating 
C point base to an H_floating point power. In FORTRAN, 

C it is not directly called. 

C- 

REAL*16 X,Y,RESULT 
X = 9877356535.0 
Y = -0.5837653 
C+ 

C In FORTRAN, OTS$POWWHH is indirectly called by simply using the 
C exponentiation operator. 

C- 

RESULT = X**Y 

TYPE 9877356535.0**-0.5837653 IS ',RESULT 
END 

This FORTRAN example demonstrates how to call OTS$POWHH_R3 to raise an 
H-floating base to an H-floating power. 

The output generated by this program is as follows: 

9877356535.0**-0.5837653 IS 1.463779145994628357482343598205427E-0006♦ 
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0TS$P0WHJ R3—Raise an H-Floating Base to a Longword 

Exponent (VAX VMS Only) 



On an OpenVMS for VAX system, the Raise an H-Floating Base to 
Exponent routine raises an H-floating base to a longword exponent. 

Format 

OTS$POWHJ_R3 

H-floating-point-base ,longword-integer-exponent 

Returns 

OpenVMS usage 

floating_point 


type 

H_floating 


access 

write only 


mechanism 

by value 

Arguments 




H-floating-point-base 


OpenVMS usage 

floating_point 


type 

H_floating 


access 

read only 


mechanism 

by value 


Base. The H-floating-point-base argument is an H-floating number containing 
the base. 


longword-integer-exponent 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 

Exponent. The longword-integer-exponent argument is a signed longword 
that contains the signed longword exponent. 


Description 

OTS$POWHJ_R3 raises an H-floating base to a longword exponent. 

The internal calculations and the floating-point result have the same precision as 
the base value. 

The floating-point result is as follows: 


Base 

Exponent 

Result 

Any 

> 0 

Product of (base**2 1 ) where i is each nonzero bit 
position in longword-integer-exponent 

> 0 

= 0 

1.0 

= 0 

= 0 

Undefined exponentiation 

< 0 

= 0 

1.0 
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Base 

Exponent 

Result 

> 0 

< 0 

1.0/ (base**2 1 ), where i is each nonzero bit position in 

longword-integer-exponent 

= 0 

< 0 

Undefined exponentiation 

< 0 

< 0 

1.0/ (base**2 1 ) where i is each nonzero bit position in 

longword-integer-exponent 


Floating-point overflow can occur. 


Undefined exponentiation occurs if the base is zero and the exponent is zero or 
negative. 

Condition Values Signaled 


SS$_FLTOVF 

MTH$_FLOOVEMAT 

MTH$_FLOUNDMAT 

MTH$_UNDEXP 


Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 
Floating-point overflow in math library. 
Floating-point underflow in math library. 

Undefined exponentiation. This error is signaled 

if H-floating-point-base is zero and longword- 
integer-exponent is zero or negative, or if the 
H-floating-point-base is negative. ♦ 
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OTS$POWII—Raise a Word Base to a Word Exponent 

The Raise a Word Base to a Word Exponent routine raises a word base to a word 
exponent. 

Format 

OTS$POWII word-integer-base ,word-integer-exponent 

Returns 

OpenVMS usage word_signed 
type word (signed) 

access write only 

mechanism by value 

Arguments 

word-integer-base 

OpenVMS usage word_signed 
type word (signed) 

access read only 

mechanism by value 

Base. The word-integer-base argument is a signed word containing the base. 

word-integer-exponent 

OpenVMS usage word_signed 
type word (signed) 

access read only 

mechanism by value 

Exponent. The word-integer-exponent argument is a signed word containing 
the exponent. 


Condition Values Signaled 

SS$_FLTDIV 

SS$_FLTOVF 

MTH$_UNDEXP 


Arithmetic trap. This error is signaled by the 
hardware if a floating-point division by zero 
occurs. 

Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 
Undefined exponentiation. This error is signaled 
if word-integer-base is zero and word- 
integer-exponent is zero or negative, or if 
word-integer-base is negative. 
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OTS$POWJ J—Raise a Longword Base to a Longword Exponent 


The Raise a Longword Base to a Longword Exponent routine raises a signed 
longword base to a signed longword exponent. 

Format 

OTS$POWJJ longword-integer-base Jongword-integer-exponent 


Returns 

OpenVMS usage longword_signed 
type longword (signed) 

access write only 

mechanism by value 


Arguments 

longword-integer-base 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 

Base. The longword-integer-base argument is a signed longword containing 
the base. 

longword-integer-exponent 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 

Exponent. The longword-integer-exponent argument is a signed longword 
containing the exponent. 

Condition Values Signaled 


SS$_FLTDIV 

SS$_FLTOVF 

MTH$_UNDEXP 


Arithmetic trap. This error is signaled by the 
hardware if a floating-point division by zero 
occurs. 

Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 

Undefined exponentiation. This error is 
signaled if longword-integer-base is zero 
and longword-integer-exponent is zero 
or negative, or if longword-integer-base is 
negative. 
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OTS$POWLULU—Raise an Unsigned Longword Base to an Unsigned 

Longword Exponent 

The Raise an Unsigned Longword Base to an Unsigned Longword Exponent 
routine raises an unsigned longword integer base to an unsigned longword 
integer exponent. 

Format 

OTS$POWLULU unsigned-lword-int-base, unsigned-lword-int-exponent 


Returns 


OpenVMS usage 

type 

access 

mechanism 


longword_unsigned 
longword (unsigned) 
write only 
by value 


Arguments 

unsigned-lword-int-base 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by value 

Unsigned longword integer base. The unsigned-lword-int-base argument 
contains the value of the integer base. 

unsigned-lword-int-exponent 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by value 

Unsigned longword integer exponent. The unsigned-lword-int-exponent 
argument contains the value of the integer exponent. 


Description 

OTS$POWLULU returns the unsigned longword integer result of raising an 
unsigned longword integer base to an unsigned longword integer exponent. Note 
that overflow cannot occur in this routine. If the result or intermediate result is 
greater than 32 bits, the low-order 32 bits are used. 

Condition Values Signaled 

MTH$_UNDEXP Both the base and exponent values are zero. 
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OTS$POWxLU—Raise a Floating-Point Base to an Unsigned 

Longword Integer Exponent 

The Raise a Floating-Point Base to an Unsigned Longword Integer Exponent 
routines raises a floating-point base to an unsigned longword integer exponent. 

Format 

OTS$POWRLU floating-point-base ,unsigned-lword-int-exponent 
OTS$POWDLU floating-point-base ,unsigned-lword-int-exponent 
OTS$POWGLU floating-point-base ,unsigned-lword-int-exponent 

OTS$POWHLU_R3 floating-point-base ,unsigned-lword-int-exponent ♦ 


Returns 


4l^!4 


Open VMS usage 

type 

access 

mechanism 


floating_point 

F_floating, D_floating, G_floating, H_floating 
write only 
by value 


Result of raising a floating-point base to an unsigned longword integer exponent. 
OTS$POWRLU returns an F-floating number. OTS$POWDLU returns a D- 
floating number. OTS$POWGLU returns a G-floating number. 


OTS$POWHLU_R3 returns an H-floating number. ♦ 


Arguments 

floating-point-base 

Open VMS usage floating_point 

tyP e F_floating, D_floating, G_floating, H_floating 

access read only 

mechanism by value 

Floating-point base. The floating-point-base argument contains the value 
of the base. For OTS$POWRLU, floating-point-base is an F-floating 
number. For OTS$POWDLU, floating-point-base is a D-floating number. 
For OTS$POWGLU, floating-point-base is a G-floating number. For 
OTS$POWHLU_R3, floating-point-base is an H-floating number. 


unsigned-lword-int-exponent 

Open VMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by value 


Integer exponent. The unsigned-lword-int-exponent argument contains the 
value of the unsigned longword integer exponent. 
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Description 


OTS$POWRLU, OTS$POWDLU, OTS$POWGLU, and 0TS$P0WHLU_R3 return 
the result of raising a floating-point base to an unsigned longword integer 
exponent. The floating-point result is as follows: 


Base 

Exponent 

Result 

Any 

> 0 

Product of (base*2 i ) where i is each nonzero bit position 

in longword-integer-exponent 

> 0 

= 0 

1.0 

= 0 

= 0 

Undefined exponentiation 

< 0 

= 0 

1.0 


Condition Values Signaled 

MTH$_FLOOVEMAT 

MTH$_FLOUNDMAT 

MTH$_UNDEXP 


Floating-point overflow in math library 
Floating-point underflow in math library. This 
can only occur if the caller has floating-point 
underflow enabled. 

Undefined exponentiation. This occurs if both the 

floating-point-base and unsigned-longword- 
integer-exponent arguments are zero. 
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OTS$POWRD Raise an F-Floating Base to a D-Floating Exponent 

The Raise an F-Floating Base to a D-Floating Exponent routine raises an F- 
floating base to a D-floating exponent. 

Format 

OTS$POWRD F-floating-point-base ,D-floating-point-exponent 

Returns 

Open VMS usage floating_point 
type D_floating 

access write only 

mechanism by value 

Arguments 

F-floating-point-base 

OpenVMS usage floating_point 
type F_floating 

access read only 

mechanism by value 

Base. The F-floating-point-base argument is an F-floating number containing 
the base. 

D-floating-point-exponent 

OpenVMS usage floating_point 
type D_floating 

access read only 

mechanism by value 

Exponent. The D-floating-point-exponent argument is a D-floating number 
that contains the exponent. 

Description 

OTS$POWRD raises an F-floating base to a D-floating exponent. 

The internal calculations and the floating-point result have the same precision as 
the base value. 

OTS$POWRD first converts the F-floating base to D-floating. The D-floating 
result for OTS$POWRD is as follows: 


Base 

Exponent 

Result 

= 0 

> 0 

0.0 

= 0 

= 0 

Undefined exponentiation 

= 0 

< 0 

Undefined exponentiation 

< 0 

Any 

Undefined exponentiation 

> 0 

> 0 

2 [exponent * LOG2(6ase)] 

> 0 

= 0 

1.0 
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Base 

Exponent 

Result 

> 0 

< 0 

2 [exponent *LOG2(base)\ 


Floating-point overflow can occur. 

Undefined exponentiation occurs if the base is zero and the exponent is zero or 
negative, or if the base is negative. 


Condition Values Signaled 

SS$_FLTOVF 

MTH$_FLOOVEMAT 

MTH$_FLOUNDMAT 

MTH$_UNDEXP 


Example 


Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 
Floating-point overflow in math library. 
Floating-point underflow in math library. 
Undefined exponentiation. This error is signaled 
if F-floating-point-base is zero and D-floating- 
point-exponent is zero or negative, or if F- 
floating-point-base is negative. 


c+ 

C This FORTRAN example demonstrates the use 
C of OTS$POWRD, which raises an F-floating point 
C base to a D-floating point exponent. The result is a 
C D-floating value. 

C- 

REAL*4 X 

REAL * 8 Y, RESULT, OTS $ POWRD 
INTEGER M(2) 

EQUIVALENCE (M(1),Y) 

X = 9768.0 

Y = 9.0 

c+ 

C The arguments of OTS$POWRD are passed by value. 

C- 

RESULT = OTS$POWRD(%VAL(X),%VAL(M(l)),%VAL(M(2))) 

TYPE *,' 9768.0**9.0 IS RESULT 
X = 7689.0 

Y = -0.587436654545 

c+ 

C In FORTRAN, OTS$POWRD is indirectly called by simply 
C using the exponentiation operator. 

C- 

RESULT = X**Y 

TYPE *,' 7689.0**-0.587436654545 IS RESULT 
END 

This FORTRAN example uses OTS$POWRD to raise an F-floating base to a 
D-floating exponent. Notice the difference in the precision of the result produced 
by this routine in comparison to the result produced by OTS$POWRR. 
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The output generated by this program is as follows: 

9768.0**9.0 IS 8.0956338648832908E+35 

7689.0**-0.587436654545 IS 5.2155199252836588E-03 
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OTS$POWRJ—Raise an F-Floating Base to a Longword Exponent 

The Raise an F-Floating Base to a Longword Exponent routine raises an F- 
floating base to a longword exponent. 

Format 

OTS$POWRJ F-floating-point-base .longword-integer-exponent 

Returns 

OpenVMS usage floating_point 
type F_floating 

access write only 

mechanism by value 

Arguments 

F-floating-point-base 

OpenVMS usage floating_point 
type F_floating 

access read only 

mechanism by value 

Base. The F-floating-point-base argument is an F-floating number containing 
the base. 

longword-integer-exponent 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by value 

Exponent. The longword-integer-exponent argument is a signed longword 
that contains the longword exponent. 

Description 

OTS$POWRJ raises an F-floating base to a longword exponent. 

The internal calculations and the floating-point result have the same precision as 
the base value. 

The floating-point result is as follows: 


Base 

Exponent 

Result 

Any 

> 0 

Product of (base**2 i ) where i is each nonzero bit 

position in longword-integer-exponent 

> 0 

= 0 

1.0 

= 0 

= 0 

Undefined exponentiation 

< 0 

= 0 

1.0 

> 0 

< 0 

1.0/ (base**2 i ), where i is each nonzero bit position in 


longword-integer-exponent 
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Base 

Exponent 

Result 

= 0 

< 0 

Undefined exponentiation 

< 0 

< 0 

1.0/ (base**2 1 ) where i is each nonzero bit position in 



longword-integer-exponent 


Floating-point overflow can occur. 


Undefined exponentiation occurs if the base is zero and the exponent is zero or 
negative. 

Condition Values Signaled 

Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 
Floating-point overflow in math library. 
Floating-point underflow in math library. 

Undefined exponentiation. This error is signaled 

if F-floating-point-base is zero and longword- 
integer-exponent is zero or negative, or if 
F-floating-point-base is negative. 


SS$_FLTOVF 

MTH$_FLOOVEMAT 

MTH$_FLOUNDMAT 

MTH$_UNDEXP 
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OTS$POWRR— Raise an F-Floating Base to an F-Floating Exponent 

The Raise an F-Floating Base to an F-Floating Exponent routine raises an 
F-floating base to an F-floating exponent. 

Format 

OTS$POWRR F-floating-point-base ,F-floating-point-exponent 

Returns 

OpenVMS usage floating_point 
type F_floating 

access write only 

mechanism by value 

Arguments 

F-floating-point-base 

OpenVMS usage floating_point 
type Fjfloating 

access read only 

mechanism by value 

Base. The F-floating-point-base argument is an F-floating number containing 
the base. 

F-floating-point-exponent 

OpenVMS usage floating_point 
type F_floating 

access read only 

mechanism by value 

Exponent. The F-floating-point-exponent argument is an F-floating number 
that contains the exponent. 


Description 

OTS$POWRR raises an F-floating base to an F-floating exponent. 

The internal calculations and the floating-point result have the same precision as 
the base value. 

The F-floating result for OTS$POWRR is as follows: 


Base 

Exponent 

Result 

= 0 

> 0 

0.0 

= 0 

= 0 

Undefined exponentiation 

= 0 

< 0 

Undefined exponentiation 

< 0 

Any 

Undefined exponentiation 

> 0 

> 0 

2 [exponent*\og 2 (base)] 

> 0 

= 0 

1.0 
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Base 

Exponent 

Result 

> 0 

< 0 

2 [< exponent*\og2{base )] 


Floating-point overflow can occur. 


Undefined exponentiation occurs if the base is zero and the exponent is zero or 
negative, or if the base is negative. 


Arithmetic trap. This error is signaled by the 
hardware if a floating-point overflow occurs. 
Floating-point overflow in math library. 
Floating-point underflow in math library. 

Undefined exponentiation. This error is signaled 

if F-floating-point-base is zero and F-floating- 
point-exponent is zero or negative, or if F- 
floating-point-base is negative. 

Example 


c+ 

C This FORTRAN example demonstrates the use 
C of 0TS$P0WRR, which raises an F-floating 
C point base to an F-floating point power. 

C- 

REAL*4 X,Y ; RESULT,OTS$POWRR 
X = 8.0 

Y = 2.0 

C+ 

C The arguments of OTS$POWRR are passed by value. 

C- 

RESULT = OTS$POWRR(%VAL(X),%VAL(Y)) 

TYPE 8.0**2.0 IS ',RESULT 
X = 9.0 

Y = -0.5 

C+ 

C In FORTRAN, OTS$POWRR is indirectly called by simply 
C using the exponentiation operator. 

C- 

RESULT = X**Y 

TYPE 9.0**-0.5 IS RESULT 
END 

This FORTRAN example uses OTS$POWRR to raise an F-floating point base to 
an F-floating point exponent. The output generated by this program is as follows: 

8.0**2.0 IS 64.00000 
9.0**-0.5 IS 0.3333333 


Condition Values Signaled 

SS$_FLTOVF 

MTH$_FLOOVEMAT 

MTH$_FLOUNDMAT 

MTH$_UNDEXP 
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OTS$SCOPY_DXDX—Copy a Source String Passed by Descriptor to 

a Destination String 

The Copy a Source String Passed by Descriptor to a Destination String routine 
copies a source string to a destination string. Both strings are passed by 
descriptor. 

Format 

OTS$SCOPY_DXDX source-string .destination-string 


corresponding jsb entry point 

OTS$SCOPY_DXDX6 

Returns 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by value 

If source-string contains more characters than destination-string, and the 
JSB entry point is used, RO contains the number of characters that were not 
copied. 

Arguments 

source-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Source string. The source-string argument is the address of a descriptor 
pointing to the source string. The descriptor class can be unspecified, fixed 
length, dynamic, scalar decimal, array, noncontiguous array, or varying. 

destination-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Destination string. The destination-string argument is the address of a 
descriptor pointing to the destination string. The class field determines the 
appropriate action. 

See the Description section for further information. 
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Description 

OTS$SCOPY_DXDX copies a source string to a destination string. All error 
conditions except truncation are signaled; truncation is ignored. 

OTS$SCOPY_DXDX passes the source string by descriptor. In addition, an 
equivalent JSB entry point is provided, with RO being the first argument 
(the descriptor of the source string), and R1 the second (the descriptor of the 
destination string). 

For the CALL entry point, RO (return status) is as it would be after a MOVC5 
instruction. For the JSB entry point, R0:R5 and the PSL are as they would be 
after a MOVC5 instruction. R0:R5 contain the following: 

RO Number of bytes of source string not moved to destination string 

R1 Address one byte beyond the last copied byte in the source string 

R2 0 

R3 Address one byte beyond the destination string 

R4 0 

R5 0 

For further information, see the VAX Architecture Reference Manual. 

Depending on the class of the destination string, the actions described below 
occur: 


Class Field 

Action 

DSC$K CLASS S,Z,SD,A,NCA 

Copy the source string. If needed, space fill 
or truncate on the right. 

DSC$K_CLASS_D 

If the area specified by the destination 
descriptor is large enough to contain the 
source string, copy the source string and 
set the new length in the destination 
descriptor. If the area specified is not 
large enough, return the previous space 
allocation (if any) and then dynamically 
allocate the amount of space needed. Copy 
the source string and set the new length 
and address in the destination descriptor. 

DSC$K_CLASS_VS 

Copy source string to destination string up 
to the limit of DSC$W_MAXSTRLEN with 
no padding. Adjust current length field to 
actual number of bytes copied. 


Condition Values Signaled 

OTS$_FATINTERR 
OTS$_INVSTRDES 
OTS$_IN S VIRMEM 


Fatal internal error. 

Invalid string descriptor. 
Insufficient virtual memory. 
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OTS$SCOPY_R_DX—Copy a Source String Passed by Reference to a 

Destination String 

The Copy a Source String Passed by Reference to a Destination String routine 
copies a source string passed by reference to a destination string. 

Format 

OTS$SCOPY_R_DX word-int-source-length-val ,source-string-address 
.destination-string 

corresponding jsb entry point 

OTS$SCOPY_R_DX6 

Returns 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by value 

If source-string-address contains more characters than destination-string, 
and the JSB entry point is used, RO contains the number of characters that were 
not copied. 

Arguments 

word-int-source-length-val 

OpenVMS usage word_unsigned 
type word (unsigned) 

access read only 

mechanism by value 

Length of the source string. The word-int-source-length-val argument is an 
unsigned word integer containing the length of the source string. 

source-string-address 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by reference 

Source string. The source-string-address argument is the address of the source 
string. 

destination-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Destination string. The destination-string argument is the address of a 
descriptor pointing to the destination string. The class field determines the 
appropriate action. The length field (DSC$W_LENGTH) alone or both the 
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address (DSC$A_POINTER) and length fields can be modified if the string is 
dynamic. For varying strings, the current length is rewritten. 

Description 

OTS$SCOPY_R_DX copies a source string to a destination string, All conditions 
except truncation are signaled; truncation is ignored. Input scalars are passed by 
value. 

OTS$SCOPY_R_DX passes the source string by reference preceded by a length 
argument. In addition, an equivalent JSB entry point is provided, with RO being 
the first argument, R1 the second, and R2 the third, if any. The length argument 
is passed in bits 15:0 of the appropriate register. 

For the CALL entry point, RO (return status) is as it would be after a MOVC5 
instruction. For the JSB entry point, R0:R5 and the PSL are as they would be 
after a MOVC5 instruction. R0:R5 contain the following: 

RO Number of bytes of source string not moved to destination string 

R1 Address one byte beyond the last copied byte in the source string 

R2 0 

R3 Address one byte beyond the destination string 

R4 0 

R5 0 

For additional information, see the VAX Architecture Reference Manual. 

Depending on the class of the destination string, the actions described below 
occur: 


Class Field 

Action 

DSC$K_CLASS_S,Z,SD,A,NCA 

Copy the source string. If needed, space fill 
or truncate on the right. 

DSC$K_CLASS_D 

If the area specified by the destination 
descriptor is large enough to contain the 
source string, copy the source string and 
set the new length in the destination 
descriptor. If the area specified is not 
large enough, return the previous space 
allocation (if any) and then dynamically 
allocate the amount of space needed. Copy 
the source string and set the new length 
and address in the destination descriptor. 

DSC$K_CLASS_VS 

Copy source string to destination string up 
to the limit of DSC$W_MAXSTRLEN with 
no padding. Adjust current length field to 
actual number of bytes copied. 
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Condition Values Signaled 

OTS$_FATINTERR 
OTS$_INVSTRDES 
OTS$_IN SVIRMEM 


Fatal internal error. 

Invalid string descriptor. 
Insufficient virtual memory. 


Example 

A FORTRAN example demonstrating dynamic string manipulation appears at the 
end of OTS$SGETl_DD. This example uses OTS$SCOPY_R_DX, OTS$SGETl_ 
DD, and OTS$SFREEl_DD. 
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0TS$SFREE1 DD—Strings, Free One Dynamic 

The Free One Dynamic String routine returns one dynamic string area to free 
storage. 

Format 

OTS$SFREE1_DD dynamic-descriptor 

corresponding jsb entry point 

OTS$SFREE1_DD6 

Returns 

None. 

Arguments 

dynamic-descriptor 

Open VMS usage quadword_unsigned 
type quadword (unsigned) 

access modify 

mechanism by reference 

Dynamic string descriptor. The dynamic-descriptor argument is the address of 
the dynamic string descriptor. The descriptor is assumed to be dynamic and its 
class field is not checked. 

Description 

OTS$SFREEl_DD deallocates the described string space and flags the descriptor 
as describing no string at all (DSC$A_POINTER = 0 and DSC$W_LENGTH = 0). 

Condition Value Signaled 

OTS$_FATINTERR Fatal internal error. 


Example 


A FORTRAN example demonstrating dynamic string manipulation appears at the 
end of OTS$SGET 1_DD. This example uses OTS$SFREEl_DD, OTS$SGETl_DD 
and OTS$SCOPY_R_DX. 
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OTS$SFREEn_DD—Strings, Free n Dynamic 

The Free n Dynamic Strings routine takes as input a vector of one or more 
dynamic string areas and returns them to free storage. 


Format 

OTS$SFREEN_DD descriptor-count-value .first-descriptor 


corresponding jsb entry point 

OTS$SFREEN_DD6 


Returns 

None. 


Arguments 

descriptor-count-value 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by value 

Number of adjacent descriptors to be flagged as having no allocated area (DSC$A_ 
POINTER = 0 and DSC$W_LENGTH = 0) and to have their allocated areas 
returned to free storage by OTS$SFREEN_DD. The descriptor-count-value 
argument is an unsigned longword containing this number. 

first-descriptor 

OpenVMS usage quadword_unsigned 
type quadword (unsigned) 

access modify 

mechanism by reference 

First string descriptor of an array of string descriptors. The first-descriptor 
argument is the address of the first string descriptor. The descriptors are 
assumed to be dynamic, and their class fields are not checked. 

Description 

OTS$SFREEN_DD6 deallocates the described string space and flags each 
descriptor as describing no string at all (DSC$A_POINTER = 0 and DSC$W_ 
LENGTH = 0). 

Condition Values Signaled 

OTS$_FATINTERR Fatal internal error. 
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0TS$SGET1 DD—Strings, Get One Dynamic 

The Get One Dynamic String routine allocates a specified number of bytes of 
dynamic virtual memory to a specified string descriptor. 

Format 

OTS$SGET1_DD word-integer-length-value .dynamic-descriptor 


corresponding jsb entry point 

OTS$SGET1_DD_R6 


Returns 

None. 


Arguments 


word-integer-len gth-value 


Open VMS usage 

type 

access 

mechanism 


word_unsigned 
word (unsigned) 
read only 
by value 


Number of bytes to be allocated. The word-integer-length-value argument 
contains the number of bytes. The amount of storage allocated is automatically 
rounded up. If the number of bytes is zero, a small number of bytes is allocated. 


dynamic-descriptor 

OpenVMS usage quadword_unsigned 
type quadword (unsigned) 

access modify 

mechanism by reference 

Dynamic string descriptor to which the area is to be allocated. The dyn-str 
argument is the address of the dynamic string descriptor. The class field is not 
checked but it is set to dynamic (DSC$B_CLASS = 2). The length field (DSC$W_ 
LENGTH) is set to word-integer-length-value and the address field (DSC$A_ 
POINTER) is set to the string area allocated (first byte beyond the header). 

Description 

OTS$SGETl_DD allocates a specified number of bytes of dynamic virtual memory 
to a specified string descriptor. This routine is identical to OTS$SCOPY_DXDX 
except that no source string is copied. You can write anything you want in the 
allocated area. 

If the specified string descriptor already has dynamic memory allocated to it, 
but the amount allocated is either greater than or less than word-integer- 
length-value, that space is deallocated before OTS$SGETl_DD allocates new 
space. 
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Condition Values Signaled 


OTS$_FATINTERR 

OTS$_INSVIRMEM 


Fatal internal error. 
Insufficient virtual memory. 


Example 


c+ 

c 

c 

c- 

c+ 

c 

c- 


c+ 

c 

c- 


c+ 

c 

c 

c- 


c+ 

c 

c- 


c+ 

c 

c- 


999 

c+ 

c 

c 

c 

c- 


998 


PROGRAM STRING_TEST 

This program demonstrates the use of some dynamic string 
manipulation routines. 


DECLARATIONS 


IMPLICIT NONE 
CHARACTER* 8 0 DATA_LINE 

INTEGER*4 DATA.LEN, DSC(2), CRLF_DSC(2), TEMP_DSC(2) 

CHARACTER*2 CRLF 

Initialize the output descriptor. It should be empty. 
CALL 0TS$SGET1_DD(%VAL(0) , DSC) 

Initialize a descriptor to the string CRLF and copy the 
character CRLF to it. 

CALL 0TS$SGET1_DD(%VAL(2), CRLF_DSC) 

CRLF = CHAR(13)//CHAR(10) 

CALL OTS$SCOPY_R_DX( %VAL(2), %REF(CRLF(1:1)), CRLF.DSC) 
Initialize a temporary descriptor. 

CALL OTS$SGET1_DD(%VAL(0) , TEMP_DSC) 

Prompt the user. 

WRITE(6, 999) 

FORMAT(IX, 'Enter your message, end with Ctrl/Z.') 

Read lines of text from the terminal until end-of-file. 
Concatenate each line to the previous input. Include a 
CRLF between each line. 

DO WHILE (.TRUE.) 

READ(5, 998, ERR = 10) DATA_LEN, DATA_LINE 
FORMAT(Q,A) 

CALL OTS$SCOPY_R_DX( %VAL(DATA_LEN), 

1 %REF(DATA_LINE(1:1)), 

2 TEMP_DSC) 

CALL STR$CONCAT( DSC, DSC, TEMP_DSC, CRLF_DSC ) 

END DO 


C+ 

C 

C 

C- 

c+ 

c 

c- 


c+ 

c 

c- 


c+ 

c 

c 

c- 


c+ 

c 

c- 


c+ 

c 

c- 


999 

c+ 

c 

c 

c 

c- 


998 
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c+ 

The user has typed Ctrl/Z. Output the data we read. 

10 CALL LIB$PUT_OUTPUT( DSC ) 

C+ 

C Free the storage allocated to the dynamic strings. 

CALL 0TS$SFREE1_DD( DSC ) 

CALL 0TS$SFREE1_DD( CRLF_DSC ) 

CALL 0TS$SFREE1_DD( TEMP_DSC ) 

C+ 

C End of program. 

C- 


STOP 

END 


This FORTRAN example program demonstrates dynamic string manipulation 
using OTS$SGETl_DD, OTS$SFREE 1_DD, and OTS$SCOPY_R_DX. 
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How to Order Additional Documentation 


Technical Support 

If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825) 
and press 2 for technical assistance. 


Electronic Orders 

If you wish to place an order through your account at the Electronic Store, dial 800-234-1998 using a 
modem set to 2400- or 9600-baud. You must be using a VT terminal or terminal emulator set at 8 bits no 
parity. If you need assistance using the Electronic Store, call 800-DIGITAL (800-344-4825) and ask for’an 
Electronic Store specialist. 


Telephone and Direct Mail Orders 


From 

U.S.A. 


Puerto Rico 


Canada 


International 


Internal Orders 1 
(for software 
documentation) 


Internal Orders 
(for hardware 
documentation) 


Call 

DECdirect 

Phone: 800-DIGITAL 
(800-344-4825) 

FAX: (603) 884-5597 

Phone: (809) 781-0505 
FAX: (809) 749-8377 


Phone: 800-267-6215 
FAX: (613) 592-1946 


DTN: 241-3023 
(508) 874-3023 


DTN: 234-4325 
(508) 351-4325 
FAX: (508) 351-4467 


Write 

Digital Equipment Corporation 
PO. Box CS2008 
Nashua, NH 03061 

Digital Equipment Caribbean, Inc. 

3 Digital Plaza, 1st Street 

Suite 200 

Metro Office Park 

San Juan, Puerto Rico 00920 

Digital Equipment of Canada Ltd. 
100 Herzberg Road 
Kanata, Ontario, Canada K2K 2A6 
Attn: DECdirect Sales 

Local Digital subsidiary or 
approved distributor 

Software Supply Business (SSB) 
Digital Equipment Corporation 
1 Digital Drive 
Westminster, MA 01473 

Publishing & Circulation Services 
Digital Equipment Corporation 
NR02-2 

444 Whitney Street 
Northboro, MA 01532 


1 Call to request an Internal Software Order Form (EN-01740-07). 
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